From c155dde091826c9939794ba50f276c756bfade4c Mon Sep 17 00:00:00 2001 From: Christopher Byrd Date: Tue, 17 Nov 2026 10:09:15 -0600 Subject: [PATCH] Home links say what they do; plain opening on How it works The closing reader groups name what each link does ("Test a server", "Call verbs from an AI agent", "Write verbs in Rust") and give the package name in the note. How it works moves to the top of the first group, where a newcomer looks first. Each destination has one name in the opening links and the closing groups, so /spec/ is "Specification overview" in both. How it works opens with a plain lead (objects at addresses, data, verbs run with a colon and a name) before the grammar. PRODUCT.md records that the home page is written for a general technical reader first while the docs pages serve the three audiences, and its evidence line gives restactd's status codes as 504/429/507. Part of #37 Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_012CEyiXRPrNfjwX3iEx99dw --- PRODUCT.md | 7 +++++-- src/pages/how-it-works.mdx | 4 +++- src/pages/index.astro | 22 +++++++++++----------- 3 files changed, 19 insertions(+), 14 deletions(-) diff --git a/PRODUCT.md b/PRODUCT.md index 1cfc838..8ab51f5 100644 --- a/PRODUCT.md +++ b/PRODUCT.md @@ -8,7 +8,10 @@ web ## Users -Three audiences, weighted equally. The site routes each to its own path rather than picking one: +The home page is written for a general technical reader first: someone who arrives from a link and has never +met the protocol. It states the problem and the idea in plain words before the mechanism, and names the +technology once for the reader who wants it. The docs pages serve three audiences, weighted equally, and the +home page routes each to its own path rather than picking one: - **Protocol reviewers**: IETF participants, HTTP and API-standards people, security reviewers. They read the draft to judge its rigour and send critique. @@ -76,7 +79,7 @@ in REST:ACT the API's clients deploy it, it runs as each caller, and it is charg - The draft and its companion documents (the extension drafts, registries), rendered under `/spec/`. - Interactive explanations: `AnatomyDemo.astro` (four requests against `notes/42`), `ResolutionWalk.astro`. -- Real behaviour from restactd: status codes 408/429/507, default limits, the `/.well-known/restact` document, +- Real behaviour from restactd: status codes 504/429/507, default limits, the `/.well-known/restact` document, verbatim shell sessions. - restactd, restact-conformance, verbsmith, restact-sdk and the agent plugins exist and are linked. - **Absent, never to be invented:** adopters, users, testimonials, benchmarks, other implementations, IETF diff --git a/src/pages/how-it-works.mdx b/src/pages/how-it-works.mdx index ebe7252..b134406 100644 --- a/src/pages/how-it-works.mdx +++ b/src/pages/how-it-works.mdx @@ -1,7 +1,7 @@ --- layout: ../layouts/MdPage.astro title: How REST:ACT works -description: A REST:ACT server is a tree of objects addressed by path. Each object has data, read and written with the standard HTTP methods, and verbs, uploaded programs addressed with a colon and invoked over HTTP. +description: A REST:ACT server holds objects at addresses, much as a disk holds files in folders. Each object has data, which you read and write with ordinary HTTP requests. It can also have verbs, small uploaded programs you run by adding a colon and the verb’s name to the object’s address. summary: A REST:ACT server is a tree of objects addressed by path. Each object has data, read and written with HTTP, and verbs, uploaded programs called over HTTP. chips: - Explanatory @@ -17,6 +17,8 @@ import ResolutionWalk from '../components/ResolutionWalk.astro'; import InRestactd from '../components/InRestactd.astro'; import { RESTACTD_DOCS } from '../site.config'; +This page shows how the server finds the verb a request names, how a function differs from an action, and what a verb is allowed to reach. + ## Objects, data and verbs An object such as `/animals/dogs/fido` has data, its JSON representation, and verbs addressed off it. The path hierarchy is a single-inheritance chain: fido's ancestors are dogs, animals and the root. diff --git a/src/pages/index.astro b/src/pages/index.astro index 768c1da..ac8d3a8 100644 --- a/src/pages/index.astro +++ b/src/pages/index.astro @@ -35,12 +35,12 @@ const abstract = [ 'Each verb is a WebAssembly component. The server runs it in a sandbox, by default with the permissions of whoever calls it, and stops it when it runs out of time or memory.', ]; -/* One next step for each of the three readers, named as the reader groups at the close name them, - then the reference server, which all three can use. */ +/* One next step for each of the three readers, then the reference server, which all three can use. + Each link carries the same name here and in the reader groups at the close: one name per page. */ const next = [ - { label: 'Review the protocol', href: DRAFT_URL }, - { label: 'Implement a server', href: '/spec/' }, - { label: 'Write and call verbs', href: '/start/' }, + { label: 'Read the draft', href: DRAFT_URL }, + { label: 'Specification overview', href: '/spec/' }, + { label: 'Get started', href: '/start/' }, { label: 'Run the reference server', href: '/restactd/' }, ]; @@ -55,25 +55,25 @@ const paths = { { reader: 'Reviewing the protocol', links: [ + { label: 'How it works', href: '/how-it-works/', body: 'Objects, verbs and how a request finds the verb it names, step by step.' }, { label: 'Read the draft', href: DRAFT_URL, body: 'Addressing, method semantics, capabilities, limits, authorization and security considerations.' }, - { label: 'Specification overview', href: '/spec/', body: 'A section-by-section map of the draft, marked core or optional.' }, { label: 'Security model', href: '/security/', body: 'The threat model and how the draft answers it.' }, ], }, { reader: 'Implementing a server', links: [ - { label: 'How it works', href: '/how-it-works/', body: 'Addressing and verb resolution, step by step.' }, - { label: 'restact-conformance', href: RESTACTD_DOCS.conformance, body: 'Black-box tests for any server, run against the features it advertises.' }, - { label: 'restactd', href: '/restactd/', body: 'The reference server, in Rust on Wasmtime: what it implements, its documentation and its source.' }, + { label: 'Specification overview', href: '/spec/', body: 'A section-by-section map of the draft, marked core or optional.' }, + { label: 'Test a server', href: RESTACTD_DOCS.conformance, body: 'restact-conformance sends black-box tests to any server, using the features it advertises.' }, + { label: 'Run the reference server', href: '/restactd/', body: 'restactd, in Rust on Wasmtime: what it implements, its documentation and its source.' }, ], }, { reader: 'Writing and calling verbs', links: [ { label: 'Get started', href: '/start/', body: 'Run restactd locally and deploy a first verb in JavaScript, Python or Rust.' }, - { label: 'restact mcp', href: GITHUB.mcp, body: 'Serves a REST:ACT host’s verbs as MCP tools.' }, - { label: 'restact-sdk', href: GITHUB.sdk, body: 'A Rust crate for writing verbs.' }, + { label: 'Call verbs from an AI agent', href: GITHUB.mcp, body: 'restact mcp serves a REST:ACT host’s verbs as MCP tools.' }, + { label: 'Write verbs in Rust', href: GITHUB.sdk, body: 'restact-sdk, a Rust crate for writing verbs.' }, ], }, ],