[sstriker]

Summary

This change writes the user documents and the rule files in ASD-STE100 (Simplified Technical English). It changes the words, not the facts.

The change does these things:

1. AGENTS.md has a new section, "Writing in ASD-STE100". The rule now applies to these files:
   • README.md, CONTRIBUTING.md and local/README.md;
   • the READMEs beside the code;
   • the Markdown documents in docs/;
   • the AGENTS files and the commands in .claude/commands/.
2. These files keep their own style: the paper, the case study (docs/seeding-a-foundation.md), PLAN.md, spikes/, examples/, code comments, the web pages and the design book.
3. A new file, docs/terms.md, gives one word for each part and idea, and the words not to use for it. It also lists the words that the documents use for a second thing.
4. Each file in scope is rewritten. One commit holds each document or group of documents.

File	Words before	Words after
README.md	4,933	5,518
local/README.md	13,723	15,732
CONTRIBUTING.md, e2e/README.md, images/harness/README.md, crates/web/companion/README.md	2,281	2,591
docs/reference-stack.md	2,354	2,632
docs/harness-containers.md	6,965	7,681
docs/llm-apache-org.md, docs/demo-narrative.md	6,544	7,201
AGENTS.md, crates/core/AGENTS.md, the two commands	4,103	4,804
Total	40,903	46,159

The text is about 13% longer, because long sentences became short sentences and lists.

How the facts were kept

Four checks ran on each file:

1. A script compared the old and new text. Headings, code blocks, link targets and inline code are the same. Some command names were added as the subject of a sentence. The script also showed that no number was lost.
2. A fresh agent checked the term list against the code before the rewrite. It found six wrong rows and ten partly wrong rows. For example, a spend limit counts tokens, not cost.
3. A fresh agent compared the old and new text of each file, sentence by sentence, and checked each added actor against the code. The checks found 14 MUST FIX items and about 70 CHECK items. All MUST FIX items are fixed. Most CHECK items are fixed too. For the others, the check itself found that the new text is correct, for example where an added actor matches the code. Examples of MUST FIX items:
   • "the egress meters recall" in the reference stack. In the planned stack, the egress does not meter recall.
   • The definition of a docs-only branch in AGENTS.md was reversed.
   • A WSL root on a \\wsl.localhost share with no --wslc-storage was said to use state/wslc-api. The code refuses it.
   • The term list said that --loop makes one session for each task. One session covers all the tasks.
4. A reader test ran on the old and the new README.md and local/README.md, with the same five questions for each. The table shows the reader's certainty and how many times it read the text to find each answer.

Document	Question	Old	New
README	Install order	sure, 1	sure, 1
README	Gateway PAT	partly, 3	partly, 3
README	Harnesses, image	fairly sure, 2	sure, 1
README	Profiles	sure, 1	sure, 2
README	API keys	sure, 1	sure, 1
local	Codex on the gateway	fairly sure, 2	fairly sure, 3
local	A held write	sure, 1	sure, 1
local	Daily token limit	fairly sure, 2	fairly sure, 2
local	Replay to another model	fairly sure, 3	sure, 3
local	Ledger on PostgreSQL	sure, 1	sure, 1

The answers are about the same. On the old README, the reader stopped at long sentences: the first sentence had 80 words, and the tools item had 90. On the new text, the reader stopped at gaps and contradictions in the facts. A rewrite that keeps the facts cannot fix these. The next section lists them.

Open: facts that the rewrite did not change

The rewriters and the readers found these problems in the facts. They are the same in the old text. Each one needs a decision, in a separate change.

• local/README.md says "eight harnesses", but its table has ten. It says "Grok is a destination, not a harness", but the table has Grok Build.
• local/README.md says that a launch with no handoff exits 4. A later section says that it no longer does.
• local/README.md says that --backend wslc --auth gateway runs LiteLLM in the session VM. Another section says that gateway auth is not connected yet.
• local/README.md says "a third of the time" for Claude Code with the record. Its own figures, 34 s against 391 s, are about one eleventh.
• local/README.md does not give the flag that names the model for amem replay, or what amem quarantine drop does.
• The README never says that the PAT goes in LLMAO_KEY, or that a gateway launch needs --auth gateway.
• images/harness/README.md says that the image holds seven harnesses and "the memory binary". It holds nine, and the binary is amem. CONTRIBUTING.md also says "the memory binary".
• docs/reference-stack.md refers to "the compose file above", which it does not have. Its crate table names crates that do not exist.
• docs/harness-containers.md says that dependabot.yml is not in .github/, but its own summary says that ci: add Dependabot version updates for GitHub Actions #12 added it.
• docs/demo-narrative.md says that dom-demo holds all 309 entries, but 309 is the count over all domains.
• AGENTS.md says "Whatever else lands in .claude/ stays ignored", but .gitignore ignores only two paths under .claude/.
• AGENTS.md says that nothing builds from or reads the Markdown files outside crates/ and taps/. But scripts/demo/11-limits.sh reads two lists in README.md. A README-only commit skips every check, so a change can break act 11 of the demo with no warning. The parser gives the same output on the old and the new README (9 and 14 items).

Adversarial pass

crates/web/companion/README.md is under crates/, so scripts/docs-only.sh does not accept this branch. Thus the adversarial pass applies, not the reader test. A fresh agent attacked the commits of this branch. It found these errors, and this change fixes them:

1. The term list mapped "wrapper" to the launcher. PLAN.md defines the wrapper as the per-session memory server and its egress. With that mapping, the root rule in AGENTS.md said that all of amem may not read an environment variable for a location. The launcher must do that, for example to find a subscription login under HOME. The rule now names the wrapper again, and the term list defines the word.
2. The guard row in AGENTS.md named fewer stash commands than the guard refuses. The guard also refuses save, pop, clear and drop.
3. A sentence in local/README.md said that the launcher files a handoff for every task. It does this only for a task that goes back to the pool.
4. The row for crates/server in AGENTS.md was circular.

It found no broken link or anchor. A script resolved 549 fragment links in the repository. No test, script or check reads a rewritten file, except the demo script in the open list above.

Revision: rebase on #33, #34 and #36

After #33, #34 and #36 merged, I rebased this branch on main. #36 changed four places that this branch rewrites. I resolved these conflicts by hand:

• AGENTS.md: the rule "No image leaves this machine" is now in ASD-STE100. The guard row names the image push, the registry login and the GitHub release.
• local/README.md: the text about hosted pages keeps the facts from fix: make an image push fail, and remove the pages workflow #36. The repository does not publish the pages, and the example site is someone.github.io/tooling-memory/. The text does not mention the removed workflow.
• images/harness/README.md: the section "Never published" is the same as on main.

Copilot found a space at the start of some wrapped lines in two documents. I found the same fault in docs/harness-containers.md. Commit 2301d96 removes these spaces and changes nothing else.

A fresh agent attacked this revision. It compared each resolved place with main, sentence by sentence. It found no lost fact. Nothing that #36 removed came back: not the pages workflow, and not the old repository name. The guard refused each class of command that the AGENTS.md row names. It found two unclear sentences, and commit b48fa77 fixes them:

• AGENTS.md said that the image check reads "the files in make check". The check reads all the files of the repository.
• In local/README.md, one "it" referred to the web launcher and the next "it" to the origin.

Checks

make check passes on the rebased branch: 718 tests run, 718 passed.

Posted by Claude on behalf of @sstriker

[Copilot]

🟡 Changes recommended

The change still has unresolved findings flagging stray leading spaces that create inconsistent Markdown source formatting across multiple lines in two docs files.

2 open issues

• Remove stray leading spaces from wrapped Markdown lines · New
• Remove stray leading spaces from wrapped Markdown lines · New

What changed in this PR

This PR rewrites the repository's user-facing documents and the AGENTS/.claude rule files into ASD-STE100 (Simplified Technical English). The stated goal is to change the wording, not the facts: long sentences become short sentences and lists. It also extends the ASD-STE100 rule (previously limited to PR/issue text and commit messages) to cover README.md, CONTRIBUTING.md, local/README.md, the READMEs beside the code, docs/ Markdown, the AGENTS files, and .claude/commands, and adds a new glossary (docs/terms.md) that fixes one word per concept.

Changes:

• Rewrites the main user docs (README, CONTRIBUTING, reference-stack, llm-apache-org, demo-narrative, e2e/companion/harness READMEs) and the rule files (AGENTS.md, crates/core/AGENTS.md, adversarial/reader-test commands) into short-sentence ASD-STE100, mostly converting run-on prose into bullet lists.
• Adds docs/terms.md (one term per concept, with "do not use" words) and .claude/commands/reader-test.md (a reader-test pass for docs-only branches).
• Updates AGENTS.md to broaden the ASD-STE100 scope and to point at docs/terms.md for the controlled vocabulary.

I verified several new factual claims against the code and they hold: the --backend values in docs/terms.md (namespaces, image, wslc, seatbelt, none, auto), the tool = true tap convention, and AGENTS.md's docs-only description against scripts/docs-only.sh. Numbers and dates in the demo narrative and llm-apache-org appear preserved. The PR explicitly lists known pre-existing factual contradictions (harness counts, the memory vs amem binary name, nonexistent crates in the reference stack) that it leaves to separate changes, so those were not re-reported.

The only concrete issue found is minor: stray single-space indents on a few wrapped paragraph lines, inconsistent with the surrounding source (harmless to rendered Markdown). Note also that this branch stacks on #33 and the reader-test branch and needs a rebase before its diff is final.

File	Description
README.md	Rewrites the proof-of-concept, "what it is", build/run, demo, and checks sections into ASD-STE100 lists; adds sandbox/egress/tunnel detail.
docs/​terms.md	New controlled vocabulary: one term per part/idea, with "do not use" words and second senses.
docs/​reference-stack.md	Reflows the stack rows/sections; adds launcher, sandbox and egress rows and a safety-boundary paragraph.
docs/​llm-apache-org.md	Reflows the gateway proposals into lists (minor stray leading spaces on two wrapped blocks).
docs/​demo-narrative.md	Reflows the act-by-act narrative; "memory calls" → "memory tool calls" (one stray-leading-space block).
images/​harness/​README.md	Reflows the harness-image notes; retains the pre-existing "seven of eight"/"memory binary" wording (acknowledged open).
e2e/​README.md	Converts the browser-test overview and spec guidance into lists.
crates/​web/​companion/​README.md	Reflows the companion extension guarantees and permissions into lists.
crates/​core/​AGENTS.md	Reflows the frontmatter-contract rules into ASD-STE100.
CONTRIBUTING.md	Reflows prerequisites and the make-target table.
AGENTS.md	Reflows the non-negotiables and adds the "Writing in ASD-STE100" section with the broadened scope and docs/terms.md pointer.
.claude/​commands/​reader-test.md	New reader-test command for docs-only branches.
.claude/​commands/​adversarial.md	Reflows the adversarial pre-PR command into steps/lists.

_{Review effort: Balanced}

[Copilot]

Warning

Copilot couldn't run its full agentic review because it didn't start before the timeout. Make sure your repository has a runner available, or add a copilot-code-review.yml file specifying one with the runs-on attribute. See the docs for more details.

Copilot review overview

2 open issues

• This states that nothing reads Markdown outside crates/ and taps/, but the PR description… · New
• This file says the image contains the memory binary, but the repository terminology (and other… · New

2 resolved since last review

• Remove stray leading spaces from wrapped Markdown lines
• Remove stray leading spaces from wrapped Markdown lines

_{Review effort: Lite}