Skip to content

Home page: plain wording for a general reader - #38

Merged
cbyrd01 merged 3 commits into
mainfrom
docs/plain-wording
Nov 17, 2026
Merged

cbyrd01 merged 3 commits into
mainfrom
docs/plain-wording

Conversation

@cbyrd01

@cbyrd01 cbyrd01 commented Nov 17, 2026

Copy link
Copy Markdown
Contributor

Part of #37

Rewrites the home page so a general technical reader can follow it, and fixes limit claims that had drifted from the draft and from restactd. This is a proposal for review: the wording is a matter of taste, so it stays a draft.

Home page

  • Opening. The two-paragraph abstract becomes three short paragraphs. The first states the problem in plain words, the second says what REST:ACT lets a user do, and the third names the technology (WebAssembly, sandbox, time and memory limits) for the reader who wants it. The title, the tagline and the four reader links are unchanged.
  • Order. "What it is for" now comes before the request demo, so the reader learns why before how. Its lead states the need, following the draft's Introduction, and its four examples are reworded plainly.
  • Rules, not a count. "What a server must implement" said six things. The draft's mandatory core now has nine items, and the page also stated the compute limit as required. The section becomes "How the server keeps uploaded code in check": four plain rules, each linked to its draft section, with /spec/ named as the full list.
  • Leads. The demo lead now says what a verb's address is. The example lead is split into short sentences.

Accuracy fixes elsewhere

  • A wall-clock breach answers 504, not 408. That matches the draft's Resource Limits section and restactd's timeout mapping. Fixed on Security (the limits table), Get started and restactd.
  • The compute limit is a SHOULD in the draft. Security, Compare, the /spec/ section gist and /llms.txt no longer state it as required.
  • Runs-as-caller is the default. The home page names the optional owner opt-in, because its own social-site example is that case.

Checks

  • astro check: 0 errors, 0 warnings, 0 hints.
  • astro build and check-site.mjs: 18 pages checked, 0 errors. These are the steps pnpm verify runs. They were run directly because a mise pnpm shim breaks the nested pnpm run here.
  • git merge-tree against origin/main: clean.
  • A separate review checked every changed claim against the draft and restactd, and checked the new text for stock phrasing. Its fixes are in the second commit.

Posted by Claude (AI assistant) on behalf of Christopher Byrd

🤖 Generated with Claude Code

https://claude.ai/code/session_012CEyiXRPrNfjwX3iEx99dw

cbyrd01 and others added 2 commits November 17, 2026 09:24
Rewrite the home page opening in plain language: the problem first, then
what REST:ACT lets a user do, then one paragraph naming the technology.
"What it is for" moves ahead of the request demo and opens with why
client code is wanted. The six-item mandatory-core grid, which no longer
matched the draft's nine items, becomes four plain rules on how the
server confines uploaded code, each linked to its draft section, with
the full list left to /spec/.

Fix limit claims that disagreed with the draft and restactd: a verb
that runs past its wall-clock limit gets 504, not 408 (Security, Get
started, restactd), and the compute limit is recommended, not required
(Security, Compare, the /spec/ section gist).

Part of #37

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012CEyiXRPrNfjwX3iEx99dw
From the text review: the runs-as-caller rule now says "by default" and
names the owner opt-in the draft allows, since the page's own social-site
example is that case. The shared deadline applies where a server lets
verbs call each other on it, matching the draft's optional composition
and its fresh budget across servers. The example lead names the second
demo request and says authentication is off rather than "no sign-in".
Security and Compare drop the last two places that stated the compute
limit as required, and /llms.txt follows the new home-page opening.

Part of #37

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012CEyiXRPrNfjwX3iEx99dw
Brings in the limit fixes from #39, which this branch also carried.
llms.txt.ts keeps this branch's summary, the short form of the new
home-page opening.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012CEyiXRPrNfjwX3iEx99dw
@cbyrd01
cbyrd01 marked this pull request as ready for review November 17, 2026 16:03
@cbyrd01
cbyrd01 merged commit f3ba2ef into main Nov 17, 2026
1 check passed
@cbyrd01
cbyrd01 deleted the docs/plain-wording branch November 17, 2026 16:03
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant