Lead agent docs with the whole-doc editing loop#143
Conversation
Agents naturally keep a local Markdown copy and sync whole documents — which is exactly what PUT /content is designed for, but the doc buried that guidance below the full API reference. Add a Quick Start section up top spelling out the canonical read → edit → PUT → 409-retry loop, with guidance on change_summary quality and not trusting stale local copies. Also state the editing model in llms.txt so agents that only read the discovery file get the right mental model. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
![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: 64c998fb4f
ℹ️ 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".
| 1. **Read** — `GET /api/v1/plans/$PLAN_ID/snapshot`. Save `current_content` to a local file and note `current_revision`. | ||
| 2. **Edit** the local file however you like. | ||
| 3. **Write** — `PUT /api/v1/plans/$PLAN_ID/content` with the full new content, `base_revision` set to the revision you read, and a specific `change_summary` (it becomes the version's label in the plan history — "Tightened rollout plan per Sam's feedback", not "Update"). |
There was a problem hiding this comment.
In host apps that mount the engine below a prefix, these root-relative endpoints send agents to the wrong app path. I checked docs/HOST_APP_GUIDE.md, which documents mount CoPlan::Engine, at: "/coplan"; in that supported configuration the snapshot/content routes are under /coplan/api/v1/..., so the new first-read editing loop would fail with 404 before agents reach the existing route-helper-based links. Please build these examples from the configured base URL/mount path or tell agents to prepend the base_url from credentials.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
🤖 Reply from Hampton's AI agent (Claude Fable).
Good catch, and it ran deeper than this section: @base was request.base_url (scheme+host only), so under a /coplan mount every curl example in the doc — pre-existing ones included — pointed at the wrong path, not just the new quick start.
Fixed at the source in 89bcfc6: @base now appends the engine's root_path, which carries the request's SCRIPT_NAME (the mount point), so all examples inherit the correct prefix in one place. The quick-start endpoints now interpolate @base too. Added specs for both mount shapes: root mount produces http://host/api/v1/... with no double slash, and a SCRIPT_NAME=/coplan request produces http://host/coplan/api/v1/....
Review feedback (Codex): the doc built every curl example from request.base_url, which drops the mount prefix — a host that mounts CoPlan at /coplan (the HOST_APP_GUIDE example) served agents examples that 404. @base now appends the engine's root_path (which carries the request's SCRIPT_NAME), fixing the new quick-start loop and every pre-existing example in one place. The quick-start endpoints now use @base too. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
1 participant
Closes out the "agents keep local MD files and upload whole versions — should we fight it?" question. Answer: no — whole-doc PUT with
base_revisionis already the designed-for path; the docs just didn't lead with it.base_revisionand a specificchange_summary→ on 409, re-read and re-apply (never retry with a stale revision). Also warns against trusting long-lived local copies.llms.txtnow states the editing model in one paragraph, so agents that only read the discovery file get the right mental model before ever fetching the full reference.Docs-only; merges independently of the other open PRs (the quick-start section is at the top of the file, #138's
replace_sectiondocs are lower down — no conflict).🤖 Generated with Claude Code