docs: add script-the-api guide (guides checkpoint 8)#43
Merged
Conversation
End-to-end guide to scripting the daemon socket API with curl: health handshake, listing sessions, launching a session, following events with the afterSeq cursor, and branching on the structured error envelope. Verified against reference/api.mdx and openapi/coven.daemon.v1.yaml. Links the final catalog row and extends check-guides-docs.mjs pins. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
Contributor
There was a problem hiding this comment.
Pull request overview
Adds the final Guides checkpoint by introducing a new “Script the API” walkthrough under content/docs/guides/, documenting a minimal, correct client loop for interacting with the Coven daemon’s local socket HTTP API.
Changes:
- Add a new guide page covering health handshake, session listing/launch, event pagination via
afterSeq, and structured error handling. - Register the new guide in the Guides nav and catalog index.
- Extend the Guides validation script with required-page/mention pins and an API-reference cross-link assertion.
Reviewed changes
Copilot reviewed 4 out of 4 changed files in this pull request and generated 2 comments.
| File | Description |
|---|---|
| scripts/check-guides-docs.mjs | Adds script-the-api to required pages, pins key API strings, and asserts a required link to the API reference. |
| content/docs/guides/script-the-api.mdx | New step-by-step guide for scripting the daemon API with curl, including events cursor and error envelope examples. |
| content/docs/guides/meta.json | Registers the new guide page in the Guides section navigation. |
| content/docs/guides/index.mdx | Links the “Script the API” row in the Guides catalog table. |
- Event loop step now covers nextCursor: null (empty page) so client loops keep their previous cursor instead of crashing - runtime_unavailable described as retryable 503, not retry-after-status Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Final checkpoint of the Guides section (#34). Stacked on #42.
Adds Script the API — the minimal correct client loop for the daemon socket API:
ok/apiVersion/ capabilities check)GET /api/v1/sessions, snake_case record shape)POST /api/v1/sessionsbody fields, project-boundary validation)afterSeqcursor (persistnextCursor.afterSeq,limitcap 1000)error.code, stable code table)Every endpoint, field name, and error code verified against
reference/api.mdxandopenapi/coven.daemon.v1.yaml.Also: links the last catalog row in
guides/index.mdx, registers the page inguides/meta.json, extendscheck-guides-docs.mjs(page + 5 mention pins + API-reference cross-link assertion).Validation: all 5 doc check scripts + validate-links (0 errors),
tsc --noEmit,next buildwithscript-the-api.htmlprerender verified.This completes the 8-checkpoint chain: #34 → #37 → #38 → #39 → #40 → #41 → #42 → this.