Add docs for coding agents

[rblalock]

I got this idea from this article: https://blog.yusu.ke/hono-cli/ . Only the riff here is instead of us having this as a CLI command (which we could do), I just add how to get our docs via the doc repo's public API. It's effectively the same thing, but just telling any coding agent to use curl instead.

I've tried it with Amp and Claude Code and it does a really good job when using these API's via curl. Some examples are below:

Questions:

1. How JS SDK KV works, and give me some examples of how to set and get it in an agent.
2. How does agent to agent comms work in the JS SDK.

Ref images on the output:

Summary by CodeRabbit

• Documentation
  • Reorganized and expanded guidance on using the documentation site and its APIs.
  • Updated section headings and clarified best-practice guidance.
  • Improved and reformatted code examples for clarity and consistency.

[coderabbitai]

Walkthrough

The agents documentation file is updated: code examples reformatted (trailing commas in function/type parameter lists and JSON formatting) and the "Best Practices" section replaced with an expanded API usage and examples section.

Changes

Cohort / File(s)	Summary
Documentation and code examples common/js/AGENTS.md	Reformat Agent function and AgentHandler type signatures to include trailing commas; adjust example JSON formatting; replace "5. Best Practices" with a new section titled "6. How to use the documentation site, its APIs, etc." that expands API usage guidance and examples.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~8 minutes

Poem

🐰 I nibbled commas, neat and small,
I hopped through docs and fixed them all,
Examples polished, headings new,
A tiny change — but cheery too. 🥕

Pre-merge checks and finishing touches

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	You can run @coderabbitai generate docstrings to improve docstring coverage.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title Check	✅ Passed	The title "Add docs for coding agents" directly corresponds to the main change in the pull request, which is updating documentation content (specifically adding a new section on "How to use the documentation site, its APIs, etc.") to enable coding agents to retrieve and use project documentation via the public API. The title is concise, specific to the change (not vague like "misc updates"), and clearly indicates that documentation is being added with a specific audience and purpose in mind. A teammate reviewing the commit history would readily understand that this PR adds documentation targeted at coding agents.

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch tips-for-agents

---

📜 Recent review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between a89adc7 and 88a0085.

📒 Files selected for processing (1)

• common/js/AGENTS.md (3 hunks)

🧰 Additional context used

📓 Path-based instructions (1)

common/{js,py}/**/*

📄 CodeRabbit inference engine (AGENT.md)

Place reusable template code under common/js and common/py

Files:

• common/js/AGENTS.md

🧠 Learnings (3)

📚 Learning: 2025-09-05T04:46:45.807Z

Learnt from: CR
PR: agentuity/templates#0
File: common/js/AGENTS.md:0-0
Timestamp: 2025-09-05T04:46:45.807Z
Learning: Applies to common/js/**/*.ts : Prefer naming the default-exported function `Agent` or the specific Agent name based on the Agent description

Applied to files:

• common/js/AGENTS.md

📚 Learning: 2025-09-05T04:47:05.202Z

Learnt from: CR
PR: agentuity/templates#0
File: common/py/AGENTS.md:0-0
Timestamp: 2025-09-05T04:47:05.202Z
Learning: Agent files should define an async function named `run(request: AgentRequest, response: AgentResponse, context: AgentContext)`

Applied to files:

• common/js/AGENTS.md

📚 Learning: 2025-09-05T04:46:45.807Z

Learnt from: CR
PR: agentuity/templates#0
File: common/js/AGENTS.md:0-0
Timestamp: 2025-09-05T04:46:45.807Z
Learning: Applies to common/js/**/*.ts : Each agent file should export a default function

Applied to files:

• common/js/AGENTS.md

🪛 LanguageTool

common/js/AGENTS.md

[grammar] ~178-~178: Use a hyphen to join words.
Context: ...tion 3. Use the url field to read full page content (see Page Content API) ###...

(QB_NEW_EN_HYPHEN)

🪛 markdownlint-cli2 (0.18.1)

common/js/AGENTS.md

118-118: Bare URL used

(MD034, no-bare-urls)

---

119-119: Bare URL used

(MD034, no-bare-urls)

---

120-120: Bare URL used

(MD034, no-bare-urls)

🔇 Additional comments (3)

common/js/AGENTS.md (3)

19-25: LGTM!

Clean reformatting of the agent function signature with trailing comma follows modern TypeScript conventions and improves consistency.

---

35-39: LGTM!

The type signature trailing comma aligns with the function signature changes and maintains consistency across the documentation.

---

122-262: Excellent documentation of API usage for coding agents.

The expanded section with curl examples, response formats, and decision matrix is well-structured and directly addresses the PR objective. Clear guidance on when to use RAG search vs. keyword search vs. page content, plus practical examples agents can copy directly—strong addition to help AI agents integrate with the documentation system.

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 2

🧹 Nitpick comments (1)

common/js/AGENTS.md (1)

178-178: Consider hyphenating compound noun for consistency. Per markdown linting, "Page-Content API" (with hyphen) is preferred to "Page Content API" (two words) when used as a compound adjective modifying "API".

Apply this diff if desired:

-2. Extract `document` items for supporting documentation
-3. Use the `url` field to read full page content (see Page Content API)
+2. Extract `document` items for supporting documentation
+3. Use the `url` field to read full page content (see Page-Content API)

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 62aff06 and a89adc7.

📒 Files selected for processing (1)

• common/js/AGENTS.md (3 hunks)

🧰 Additional context used

📓 Path-based instructions (1)

common/{js,py}/**/*

📄 CodeRabbit inference engine (AGENT.md)

Place reusable template code under common/js and common/py

Files:

• common/js/AGENTS.md

🧠 Learnings (3)

📚 Learning: 2025-09-05T04:46:45.807Z

Learnt from: CR
PR: agentuity/templates#0
File: common/js/AGENTS.md:0-0
Timestamp: 2025-09-05T04:46:45.807Z
Learning: Applies to common/js/**/*.ts : Prefer naming the default-exported function `Agent` or the specific Agent name based on the Agent description

Applied to files:

• common/js/AGENTS.md

📚 Learning: 2025-09-05T04:47:05.202Z

Learnt from: CR
PR: agentuity/templates#0
File: common/py/AGENTS.md:0-0
Timestamp: 2025-09-05T04:47:05.202Z
Learning: Agent files should define an async function named `run(request: AgentRequest, response: AgentResponse, context: AgentContext)`

Applied to files:

• common/js/AGENTS.md

📚 Learning: 2025-09-05T04:46:45.807Z

Learnt from: CR
PR: agentuity/templates#0
File: common/js/AGENTS.md:0-0
Timestamp: 2025-09-05T04:46:45.807Z
Learning: Applies to common/js/**/*.ts : Each agent file should export a default function

Applied to files:

• common/js/AGENTS.md

🪛 LanguageTool

common/js/AGENTS.md

[grammar] ~178-~178: Use a hyphen to join words.
Context: ...tion 3. Use the url field to read full page content (see Page Content API) ###...

(QB_NEW_EN_HYPHEN)

🪛 markdownlint-cli2 (0.18.1)

common/js/AGENTS.md

118-118: Bare URL used

(MD034, no-bare-urls)

---

119-119: Bare URL used

(MD034, no-bare-urls)

---

120-120: Bare URL used

(MD034, no-bare-urls)

🔇 Additional comments (3)

common/js/AGENTS.md (3)

19-23: Function signature reformatting looks good. The multi-line format with trailing comma improves readability and aligns with modern TypeScript conventions.

---

35-39: Type signature formatting is consistent. The trailing comma after the context parameter aligns with the function example formatting and modern TypeScript style.

---

114-262: New API documentation section is well-structured and comprehensive. The coverage of three distinct API endpoints (RAG Search, Keyword Search, Page Content) with practical curl examples, response formats, and decision guidance provides agents with clear patterns for fetching documentation programmatically. This aligns well with the PR objective of enabling agents to retrieve docs via the public API.