Skip to content

docs: rewrite READMEs for readability and split long guides into docs/ - #234

Merged
ThomasK33 merged 10 commits into
mainfrom
docs-ahhh
Sep 24, 2026
Merged

docs: rewrite READMEs for readability and split long guides into docs/#234
ThomasK33 merged 10 commits into
mainfrom
docs-ahhh

Conversation

@ThomasK33

@ThomasK33 ThomasK33 commented Sep 24, 2026 •
edited
Loading

Copy link
Copy Markdown
Member

Rewrites the READMEs and project docs for readability: shorter prose, tables instead of paragraphs, and long how-to sections moved into per-package docs/ guides. The agent README goes from 1,862 to ~830 lines (rendered page −61%).

What changed

Doc Words before → after Change
Root README.md 935 → 784 (mostly code) One-line package table, "Which package?" table, numbered compose steps, short "Go deeper" list
packages/agent/README.md 14,407 → 4,913 Contents table; sections grouped into get started / build / reference / production
packages/sandbox/README.md 3,551 → 2,507 Settings and requirements as tables
packages/provider/README.md 2,121 → 1,212 Security reference moved out; README keeps 6 key points
effect, release-please-ai, CONTRIBUTING, examples visible prose −27–35% Tightened; background moved into <details>

New guides (each old README heading keeps a short summary + link, so existing anchors still resolve):

  • packages/agent/docs/: durable-workflows.md, workspaces-and-quota.md, observability.md, structured-output.md
  • packages/sandbox/docs/template-authoring.md
  • packages/provider/docs/security.md

docs is added to files in the agent, sandbox, and provider package.json, so these links also resolve in installed packages.

Content was relocated, not deleted: total words across all docs are roughly unchanged (24.7k → 24.5k); visible README prose dropped 30–48%.

Factual corrections

Verification tier: verified against source.

  1. Root README no longer says "Coder's chat API is experimental". The agent package targets the stable /api/v2/chats (Coder 2.37.0) with a 404 fallback to the experimental prefix (packages/agent/src/coder/client.ts).
  2. Agent README said each CoderAgent "may provision a workspace", contradicting "This SDK never provisions workspaces". Now: "bound to at most one workspace".

Validation

  • Three independent fact auditors compared every claim against 2c1d888. They found one meaning change: a table applied the timeout-only cutShort pin to stream_closed too. It is fixed in 08611ee, together with two stale rule links.
  • All README and guide TS snippets typecheck (assembled into scratch files under each package's examples/).
  • pnpm check passes. A relative link + anchor checker over all tracked Markdown finds 0 broken links.

Screenshots

Rendered via GitHub's markdown API.

Root README, before:

Root README before

Root README, after:

Root README after

Agent README, after (contents table):

Agent README after

Follow-up PR (stacked) fixes pre-existing inaccuracies found during the rewrite (requestTimeoutMs wording, BYOK qualifier, release-please-ai overstatement, a non-compiling snippet placeholder, links to paths not shipped in npm packages).

Generated with xum • Model: anthropic:claude-opus-5-5 • Thinking: high

@ThomasK33
docs: tighten root README and CONTRIBUTING
e02f30a 
Change-Id: I41f9bade8b8ace222cf694ce9f0024ebc50ba8cf
Signed-off-by: Thomas Kosiewski <tk@coder.com>
@ThomasK33
docs(sandbox): tighten README and move template guide to docs
f27ff99 
Shorten the sandbox README's main reading path: tables for transports,
workspace requirements, ensureCoderWorkspace settings, and lifecycle modes;
transport rationale in collapsible blocks; Development trimmed to the
package-specific e2e commands. Move the zero-install template authoring
guide to packages/sandbox/docs/template-authoring.md, keeping a summary
under the same README heading so anchors still resolve.

Signed-off-by: Thomas Kosiewski <tk@coder.com>
@ThomasK33
docs(provider): tighten README and move security reference to docs/se…
06bafd0 
…curity.md

Change-Id: I7e13f8a135436171e10959f2a8e189e4b7c52fbb
Signed-off-by: Thomas Kosiewski <tk@coder.com>
@ThomasK33
docs(effect): tighten README
44514c3 
Change-Id: I0f1c1c369b1b1cae3cb3d5112e6f3fe4bc8050cb
Signed-off-by: Thomas Kosiewski <tk@coder.com>
@ThomasK33
docs: tighten release-please-ai README
5ef13e4 
Change-Id: Ib15397d81356a03cb3552404db0d7d19cd769982
Signed-off-by: Thomas Kosiewski <tk@coder.com>
@ThomasK33
docs(agent): tighten README and move deep dives to docs/
c3adcc0 
Rewrite packages/agent/README.md for skimming: result-first sections,
tables for options/errors/return values, and internals in <details>.
Move the transport-event reference to docs/observability.md and the
structured_output tool pattern to docs/structured-output.md, keeping
short summaries under the same headings. Replace the Workspaces & quota
and Durable workflows sections with summaries that link to their new
docs files (written separately).

Signed-off-by: Thomas Kosiewski <tk@coder.com>
@ThomasK33
docs(agent): add durable-workflows and workspaces guides
d7fa382 
Extract the Workspaces & quota and Durable workflows README sections into standalone guides under packages/agent/docs/, restructured for skimming: tables for options and error types, edge cases and protocol internals moved into <details> blocks. Former ### headings are kept as ## with identical text so anchors resolve.

Signed-off-by: Thomas Kosiewski <tk@coder.com>
@ThomasK33
docs(agent): group README sections and add contents table
163fe06 
Change-Id: I33368a8f75e4a0f5da1a315a00418d195d9e26c2
Signed-off-by: Thomas Kosiewski <tk@coder.com>
@ThomasK33
docs(agent): scope cutShort pin to timeouts and point rule links at s…
08611ee 
…tructured-output guide

Change-Id: I9af034917593a3063392a959edb0ab2efa0523f1
Signed-off-by: Thomas Kosiewski <tk@coder.com>
@ThomasK33

ThomasK33 commented Sep 24, 2026

Copy link
Copy Markdown
Member Author

@codex review

@ThomasK33

ThomasK33 commented Sep 24, 2026

Copy link
Copy Markdown
Member Author

@codex security review

@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Sep 24, 2026 •
edited
Loading

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-24T10:35:46.545095Z c23533c Manual request
🔒 Security Review ✅ Completed 2026-09-24T10:39:25.675739Z c23533c Manual request
ℹ️ 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 commented Sep 24, 2026

Copy link
Copy Markdown

🛡️ Codex Security Review

Security review completed. No security issues were found in this pull request.

Reviewed commit: 08611ee70b

View security finding report

Only the user who started this review can view the report in Codex.

ℹ️ About Codex security reviews in GitHub

This is an experimental Codex feature. Security reviews are triggered when:

  • You comment "@codex security review"
  • A regular code review gets triggered (for example, "@codex review" or when a PR is opened), and you’re opted in so security review runs alongside code review

Once complete, Codex will leave suggestions, or a comment if no findings are found.

chatgpt-codex-connector[bot]
chatgpt-codex-connector Bot reviewed Sep 24, 2026
View reviewed changes

@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: 08611ee70b

ℹ️ 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 packages/agent/README.md
@ThomasK33 ThomasK33 mentioned this pull request Sep 24, 2026
Merged
@ThomasK33
build: ship docs/ in the agent, sandbox, and provider npm packages
c23533c 
Change-Id: I4e94061f65d31cc017ec19e2aabf2d9af49a542e
Signed-off-by: Thomas Kosiewski <tk@coder.com>
@ThomasK33

ThomasK33 commented Sep 24, 2026

Copy link
Copy Markdown
Member Author

@codex review

@ThomasK33

ThomasK33 commented Sep 24, 2026

Copy link
Copy Markdown
Member Author

@codex security review

@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Sep 24, 2026

Copy link
Copy Markdown

Codex Review: Something went wrong. Try again later by commenting “@codex review”.

Provided git ref c23533c2e022aa9fcfd723f75111a7290113a3e5 does not exist
ℹ️ 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".

@ThomasK33

ThomasK33 commented Sep 24, 2026

Copy link
Copy Markdown
Member Author

@codex review

@ThomasK33

ThomasK33 commented Sep 24, 2026

Copy link
Copy Markdown
Member Author

@codex security review

@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Sep 24, 2026

Copy link
Copy Markdown

Codex Review: Didn't find any major issues. Hooray!

Reviewed commit: c23533c2e0

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

@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Sep 24, 2026

Copy link
Copy Markdown

🛡️ Codex Security Review

Security review completed. No security issues were found in this pull request.

Reviewed commit: c23533c2e0

View security finding report

Only the user who started this review can view the report in Codex.

ℹ️ About Codex security reviews in GitHub

This is an experimental Codex feature. Security reviews are triggered when:

  • You comment "@codex security review"
  • A regular code review gets triggered (for example, "@codex review" or when a PR is opened), and you’re opted in so security review runs alongside code review

Once complete, Codex will leave suggestions, or a comment if no findings are found.

@ThomasK33
ThomasK33 added this pull request to the merge queue Sep 24, 2026
Merged via the queue into main with commit 1c5079b Sep 24, 2026
8 checks passed
@ThomasK33
ThomasK33 deleted the docs-ahhh branch September 24, 2026 10:42
This was referenced Sep 24, 2026
Merged
Merged
Merged
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@chatgpt-codex-connector chatgpt-codex-connector[bot] chatgpt-codex-connector[bot] left review comments

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@ThomasK33