Skip to content

docs(site): reshape the remaining Base Registry tutorials - #921

Merged
jeremi merged 3 commits into
mainfrom
docs/breg-tutorials-review
Sep 8, 2026
Merged

docs(site): reshape the remaining Base Registry tutorials#921
jeremi merged 3 commits into
mainfrom
docs/breg-tutorials-review

Conversation

@jeremi

@jeremi jeremi commented Sep 7, 2026

Copy link
Copy Markdown
Member

Summary

Applies the tutorial-shape rules from #919 to the six Base Registry tutorials after first-breg and derive, and re-verifies every transcript on the current development build.

  • Extend a registry with a module: reads the module's version and field lines instead of reprinting the file; the project-open step no longer restates the first tutorial's records.
  • Review changes before updating a registry: numbered headings dropped; the profile table, config reprint, and journey route table replaced by the stage and changeControl lines the reader edits, with links to the configure and API reference pages; the 26-finding transcript quotes the first group and the summary line; the direct-write refusal is quoted verbatim; one action per heading.
  • Send registry events to a webhook: replayed with no differences, review date only.
  • Query a spatial registry from QGIS: drops the unused uv prerequisite, trims the bounding box and row boundary explanations, and corrects the claim about rerunning the import: a complete checkpoint sends nothing but the summary repeats the checkpoint's counts rather than reporting zero items.
  • Build a production candidate: prerequisite no longer names a fixed bregctl version; the PostgreSQL step no longer refers to a launcher the page never uses. All digests replayed identically.
  • Query a registry from Python and Node: intro and error-kind inventory shortened with a link to the client API reference; the paging step now says the order follows the assigned identifiers (a list without orderby is sorted by record identifier, and orderby on code is refused because the project declares no sort fields); the troubleshooting rows for missing environment variables now match what Python and Node actually raise.

Verification

  • Every command on the six pages replayed against the development build of breg, bregctl, and mint from main; the module, review-changes, webhook, candidate, and client pages matched their transcripts apart from the two corrections above. The QGIS launcher banner and import block matched; the QGIS desktop steps were not replayed.
  • The published clients were installed at 0.27.0 by hand because the development binary reports 0.27.0-dev.
  • npm run check:evidence-anchors and npm run check in docs/site pass.

Follow-ups not in this PR

  • The review-changes tutorial still clones the repository and borrows the quickstart database; it could run on bregctl dev if the acceptance example shipped environment: local and a dev-clients.yaml.
  • The two draft tutorials (deploy-evidence-from-breg, evidence-from-breg) were not reviewed.
  • verify.package.package_refused, which appears when verify runs against the unedited runtime-test copy, is not in the candidate troubleshooting table.

Apply the tutorial-shape rules to the six Base Registry tutorials that
follow the first two: every screen keeps a command or a line to check,
role and route inventories move to the configure and reference pages,
generated files are no longer reprinted, and headings name the action.
Every transcript was replayed on the current development build. Two
claims did not hold and are corrected: a repeated data import prints
the checkpoint's cumulative count rather than zero, and a list without
orderby is sorted by the assigned identifier, so the paging order is
not the creation order.

Signed-off-by: Jeremi Joslin <jeremi@joslin.fr>
@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Sep 7, 2026

Copy link
Copy Markdown

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review Completed 2026-09-08T03:08:16.601946Z b942d21 New commits
ℹ️ 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" or "@codex security review".

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 chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: e1a7ba92f7

ℹ️ 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".

Comment thread docs/site/src/content/docs/tutorials/query-a-spatial-registry-from-qgis.mdx Outdated
Comment thread docs/site/src/content/docs/tutorials/review-registry-changes.mdx Outdated
The spatial quickstart launcher requires uv, so the QGIS prerequisites
name it again. The module and review-changes pages say every check
repeats the findings, but each page later shows a refused check that
prints errors and no findings, so the claim now applies to checks that
pass.

Signed-off-by: Jeremi Joslin <jeremi@joslin.fr>

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: b942d21caf

ℹ️ 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".

Comment thread docs/site/src/content/docs/tutorials/review-registry-changes.mdx Outdated
…ndings summary

The four correction profiles each declare a required scope, so they are
absent from the no_required_scope group, and two of them are granted no
list operation at all. The summary said the other three codes said the
same of other grants, which read as though any authenticated caller
could select every profile and list every row.

Signed-off-by: Jeremi Joslin <jeremi@joslin.fr>
@jeremi
jeremi merged commit 7a91e17 into main Sep 8, 2026
37 checks passed
@jeremi
jeremi deleted the docs/breg-tutorials-review branch September 8, 2026 03:50
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