docs(site): state the shape a tutorial keeps and what a shown request proves - #919
docs(site): state the shape a tutorial keeps and what a shown request proves#919jeremi wants to merge 2 commits into
Conversation
… proves Signed-off-by: Jeremi Joslin <jeremi@joslin.fr>
Codex Review SummaryThis comment shows the latest Codex review activity on this pull request.
ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings. |
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 7787ed6513
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: b955ead8ca
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| - For keyboard shortcuts, use backticks: `Ctrl+C`. Inline HTML, including `<kbd>`, fails the markdownlint gate (MD033). | ||
| - Show output only if you ran the command and read what came back. An unobserved transcript is a claim without evidence, and Principle 2 applies to it exactly as it applies to prose. If you cannot run the command, write a sentence for what happens instead: "the command prints the key ID and exits 0". | ||
| - Never invent a banner, a log line, a progress message, or a version string. If nobody has seen the software print it, it is not output. | ||
| - A request the page shows was sent as written, at that path and with that body, to a running instance that answered with the status the page names. A body inferred from a schema is a guess: the envelope, the field casing, and the query parameters are exactly what a schema does not tell you. |
There was a problem hiding this comment.
For any request containing the required <placeholder>, example.com, or fake token from lines 145-146, the literal request shown cannot have been sent “as written” to a running instance. This makes the new verification rule impossible to satisfy without either exposing real values or making a false replay claim; require the displayed request shape and body to have been tested while allowing clearly documented substitutions for redacted or reader-supplied values.
Useful? React with 👍 / 👎.
| - Link into another page's section when the reader wants that section and not the page: a procedure they were sent to perform, a definition they were sent to check. Link to the page itself when they need its context to make sense of the part. `check-built-links` resolves every fragment against the built page, so a renamed heading fails the build rather than dropping the reader silently at the top. | ||
| - Link to upstream standards bodies first, then to mirrors or summaries. | ||
| - Pin links to code to a release tag (`v0.8.3`) or a commit SHA, never a branch, when the claim depends on the code state. | ||
| - The generated CLI reference under `reference/cli/` is `draft: true` on the unreleased docset and is published from release archives only, so a current page must not link into it: `check-built-links` fails the build. Send the reader to `<command> --help` instead. |
There was a problem hiding this comment.
This adds factual source-repository assertions about the generated pages' draft state, archive-only publication, and the exact failure behavior of check-built-links, but provides no evidence anchor for any of them. Because this sentence becomes binding guidance for all current pages, an implementation or publication change can leave authors following a stale rule without the evidence check detecting it; cite the relevant metadata and archive/link-check implementation, or mark the unsupported part with TODO[evidence] and weaken it.
AGENTS.md reference: docs/site/AGENTS.md:L27-L30
Useful? React with 👍 / 👎.
1 participant
Rules the two BReg tutorial rewrites in #918 needed and the style guide did not yet state.
--helpinstead of linking into it.Vale and markdownlint pass. Prose only, no page content changed.