Skip to content

Home links say what they do; plain opening on How it works - #40

Merged
cbyrd01 merged 1 commit into
mainfrom
docs/37-link-labels
Nov 17, 2026
Merged

cbyrd01 merged 1 commit into
mainfrom
docs/37-link-labels

Conversation

@cbyrd01

@cbyrd01 cbyrd01 commented Nov 17, 2026

Copy link
Copy Markdown
Contributor

Part of #37

The approved follow-ups from the wording review: questions 4 and 5, and question 1's PRODUCT.md note.

Home page links

  • The closing reader groups say what each link does, and the note names the package:
    • restact-conformance becomes Test a server.
    • restact mcp becomes Call verbs from an AI agent.
    • restact-sdk becomes Write verbs in Rust.
    • restactd becomes Run the reference server.
  • How it works moves to the top of the first group ("Reviewing the protocol"). Its note now says what the page covers. Specification overview moves to the top of "Implementing a server", where it replaces How it works.
  • Each destination has one name in the opening links and the closing groups:
    • /spec/ is "Specification overview" in both places. It was "Implement a server" in the opening.
    • The draft is "Read the draft" in both. It was "Review the protocol".
    • /start/ is "Get started" in both. It was "Write and call verbs".

How it works

The lead was "A REST:ACT server is a tree of objects addressed by path…". It is now a plain opening: objects at addresses, data you read and write with ordinary HTTP requests, and verbs you run by adding a colon and the verb's name. One line after it says what the page covers. The grammar is unchanged.

PRODUCT.md

  • Records that the home page is written for a general technical reader first, and that the docs pages serve the three audiences.
  • The evidence line gives restactd's status codes as 504/429/507.

Checks

  • astro check: 0 errors, 0 warnings, 0 hints.
  • astro build and check-site.mjs: 18 pages checked, 0 errors.
  • git merge-tree against origin/main: clean.
  • The home page's closing groups and the How it works lead were checked in a headless browser at desktop width.

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

🤖 Generated with Claude Code

https://claude.ai/code/session_012CEyiXRPrNfjwX3iEx99dw

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 <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:10
@cbyrd01
cbyrd01 merged commit 796d5c2 into main Nov 17, 2026
1 check passed
@cbyrd01
cbyrd01 deleted the docs/37-link-labels branch November 17, 2026 16:10
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