Skip to content

Commit cf4d0ec

Browse files
patnikopatniko
committed
docs: Documentation improvement plan
Summary of audit findings: - 8 critical/high priority issues (mostly Go examples missing context param) - 4 medium priority issues (broken link, incorrect field names) - 5 low priority improvements (API reference, events docs, cookbook) Most impactful fixes needed: 1. Go CreateSession examples need context.Context parameter 2. Go NewClient returns *Client not (*Client, error) 3. Session persistence guide uses non-existent method names 4. Error handling doc references non-existent fields
1 parent 832ef77 commit cf4d0ec

1 file changed

Lines changed: 334 additions & 0 deletions

File tree

‎docs/IMPROVEMENT_PLAN.md‎

Lines changed: 334 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,334 @@
1+
# Documentation Improvement Plan
2+
3+
Generated: 2026-02-03
4+
Audited by: docs-maintenance agent
5+
6+
## Summary
7+
8+
- **Coverage**: ~85% of SDK features documented
9+
- **Sample Accuracy**: 8 issues found (mostly in Go examples missing context parameter)
10+
- **Link Health**: 1 broken link
11+
- **Multi-language**: All docs have 4-language examples ✓
12+
13+
---
14+
15+
## Critical Issues (Fix Immediately)
16+
17+
### 1. Go Examples Missing Context Parameter
18+
19+
- **Files**: Multiple docs
20+
- **Problem**: Go SDK's `CreateSession` requires `context.Context` as first parameter, but many docs show it without context
21+
- **Impact**: Examples won't compile
22+
23+
**Files affected:**
24+
- `docs/hooks/overview.md` (lines 97, 98)
25+
- `docs/hooks/pre-tool-use.md` (line 129)
26+
- `docs/hooks/post-tool-use.md` (line 122)
27+
- `docs/hooks/user-prompt-submitted.md` (line 116)
28+
- `docs/hooks/session-lifecycle.md` (multiple)
29+
- `docs/hooks/error-handling.md` (line 123)
30+
- `docs/debugging.md` (lines 50-52, 170-173, 225)
31+
- `docs/auth/index.md` (lines 125-129)
32+
- `docs/auth/byok.md` (lines 111-121)
33+
34+
**Example fix for `docs/hooks/overview.md` line 97-98:**
35+
36+
```go
37+
// Current (wrong):
38+
client, _ := copilot.NewClient(copilot.ClientOptions{})
39+
session, _ := client.CreateSession(ctx, copilot.SessionConfig{
40+
41+
// Should be:
42+
client := copilot.NewClient(nil)
43+
session, err := client.CreateSession(context.Background(), &copilot.SessionConfig{
44+
```
45+
46+
### 2. Go NewClient Takes Pointer
47+
48+
- **Files**: `docs/hooks/overview.md`, `docs/debugging.md`
49+
- **Problem**: `NewClient` takes `*ClientOptions` not `ClientOptions`
50+
- **Impact**: Examples won't compile
51+
52+
**Example fix:**
53+
54+
```go
55+
// Current (wrong):
56+
client, _ := copilot.NewClient(copilot.ClientOptions{})
57+
58+
// Should be:
59+
client := copilot.NewClient(nil) // or
60+
client := copilot.NewClient(&copilot.ClientOptions{LogLevel: "debug"})
61+
```
62+
63+
### 3. Go NewClient Returns Only Client (Not Error)
64+
65+
- **Files**: `docs/debugging.md` (lines 50-52, 170-173, 225)
66+
- **Problem**: Docs show `client, err := copilot.NewClient(...)` but `NewClient` returns only `*Client`
67+
- **Impact**: Examples won't compile
68+
69+
**Fix:**
70+
71+
```go
72+
// Current (wrong):
73+
client, err := copilot.NewClient(copilot.ClientOptions{...})
74+
75+
// Should be:
76+
client := copilot.NewClient(&copilot.ClientOptions{...})
77+
```
78+
79+
---
80+
81+
## High Priority (Should Fix Soon)
82+
83+
### 1. Session Persistence Guide Has Wrong Method Names
84+
85+
- **File**: `docs/guides/session-persistence.md`
86+
- **Lines**: Multiple
87+
- **Problem**: Uses non-existent methods like `sendPrompt`, `CreateSessionOptions`, `PromptOptions`
88+
- **Fix**: Update to use correct API methods
89+
90+
**TypeScript fixes needed:**
91+
92+
```typescript
93+
// Current (wrong):
94+
await session.sendPrompt({ content: "..." });
95+
96+
// Should be:
97+
await session.send({ prompt: "..." });
98+
// or
99+
await session.sendAndWait({ prompt: "..." });
100+
```
101+
102+
**Python fixes needed:**
103+
104+
```python
105+
# Current (wrong):
106+
await session.send_prompt(content="...")
107+
108+
# Should be:
109+
await session.send({"prompt": "..."})
110+
# or
111+
await session.send_and_wait({"prompt": "..."})
112+
```
113+
114+
**Go fixes needed:**
115+
116+
```go
117+
// Current (wrong):
118+
session.SendPrompt(copilot.PromptOptions{Content: "..."})
119+
120+
// Should be:
121+
session.SendAndWait(copilot.MessageOptions{Prompt: "..."}, 0)
122+
```
123+
124+
**C# fixes needed:**
125+
126+
```csharp
127+
// Current (wrong):
128+
await session.SendPromptAsync(new PromptOptions { Content = "..." });
129+
130+
// Should be:
131+
await session.SendAndWaitAsync(new MessageOptions { Prompt = "..." });
132+
```
133+
134+
### 2. Error Handling Doc Has Non-Existent Fields
135+
136+
- **File**: `docs/hooks/error-handling.md`
137+
- **Lines**: ~148-158, 174-185, 200-210
138+
- **Problem**: References `input.errorType` and `input.stack` but actual type uses `input.errorContext` and `input.error` (no stack)
139+
- **Fix**: Update to match actual `ErrorOccurredHookInput` type
140+
141+
```typescript
142+
// Current (wrong):
143+
input.errorType
144+
input.stack
145+
146+
// Should be:
147+
input.errorContext // "model_call" | "tool_execution" | "system" | "user_input"
148+
input.error // string error message
149+
```
150+
151+
### 3. User Prompt Submitted Hook Uses Non-Existent Output Fields
152+
153+
- **File**: `docs/hooks/user-prompt-submitted.md`
154+
- **Lines**: ~207-218, 227-238
155+
- **Problem**: Examples use `reject` and `rejectReason` which don't exist in `UserPromptSubmittedHookOutput`
156+
- **Fix**: Update to use actual output fields
157+
158+
```typescript
159+
// Current (wrong):
160+
return {
161+
reject: true,
162+
rejectReason: "..."
163+
};
164+
165+
// The actual UserPromptSubmittedHookOutput has:
166+
// - modifiedPrompt?: string
167+
// - additionalContext?: string
168+
// - suppressOutput?: boolean
169+
170+
// Alternative: throw an error or use a different approach
171+
```
172+
173+
---
174+
175+
## Medium Priority (Nice to Have)
176+
177+
### 1. Broken Link in Getting Started
178+
179+
- **File**: `docs/getting-started.md`
180+
- **Line**: ~1023
181+
- **Problem**: Link to `./mcp.md` should be `./mcp/overview.md`
182+
183+
```markdown
184+
<!-- Current (broken): -->
185+
📖 **[Full MCP documentation →](./mcp.md)**
186+
187+
<!-- Should be: -->
188+
📖 **[Full MCP documentation →](./mcp/overview.md)**
189+
```
190+
191+
### 2. Python Hook Invocation Uses Dict Instead of Object
192+
193+
- **Files**: `docs/hooks/pre-tool-use.md`, `docs/hooks/post-tool-use.md`, `docs/hooks/user-prompt-submitted.md`, `docs/hooks/session-lifecycle.md`, `docs/hooks/error-handling.md`
194+
- **Problem**: Examples show `invocation['session_id']` but Python SDK uses `invocation.session_id` (it's an object, not a dict)
195+
- **Note**: Need to verify actual Python SDK implementation - if it passes dict, this is correct; if object, needs update
196+
197+
### 3. Go SessionConfig Should Be Pointer
198+
199+
- **Files**: Multiple hook docs
200+
- **Problem**: Some examples show `copilot.SessionConfig{}` directly, should be `&copilot.SessionConfig{}`
201+
- **Fix**: Add `&` before struct literals
202+
203+
### 4. .NET Async Pattern Missing CancellationToken
204+
205+
- **Files**: Multiple docs
206+
- **Problem**: .NET async examples don't show `CancellationToken` usage which is best practice
207+
- **Note**: Low priority since methods work without it, but documentation could show the pattern
208+
209+
---
210+
211+
## Low Priority (Future Improvement)
212+
213+
### 1. Add API Reference Documentation
214+
215+
- **Location**: Consider adding `docs/api/` directory
216+
- **Problem**: No auto-generated API reference docs
217+
- **Suggestion**: Add TypeDoc/JSDoc extraction for Node.js, pdoc for Python, godoc for Go, and xmldoc for .NET
218+
219+
### 2. Add Events Reference
220+
221+
- **Location**: Consider `docs/events/` or `docs/api/events.md`
222+
- **Problem**: No comprehensive list of all ~40+ event types with their data structures
223+
- **Suggestion**: Generate from `SessionEvent` type definitions
224+
225+
### 3. Add Cookbook/Recipes Section
226+
227+
- **Location**: `docs/cookbook/` or `docs/recipes/`
228+
- **Problem**: Advanced patterns not well documented
229+
- **Suggestions**:
230+
- Building a code reviewer agent
231+
- Multi-turn conversation with context
232+
- Rate limiting and retry patterns
233+
- Production deployment checklist
234+
235+
### 4. Document ResumeSessionConfig Fully
236+
237+
- **File**: Consider adding to `docs/guides/session-persistence.md`
238+
- **Problem**: `ResumeSessionConfig` type has many options not fully documented
239+
240+
---
241+
242+
## Missing Documentation
243+
244+
The following SDK features could use dedicated documentation:
245+
246+
- [ ] `onUserInputRequest` handler - add to hooks or guides
247+
- [ ] `skillDirectories` and custom skills - no dedicated docs
248+
- [ ] `availableTools` / `excludedTools` - mentioned but not explained in depth
249+
- [ ] `configDir` option - undocumented
250+
- [ ] Session export (`ExportSessionOptions`) - mentioned in compatibility but no guide
251+
- [ ] `cliArgs` option - useful for advanced CLI flags
252+
253+
---
254+
255+
## Sample Code Fixes Needed
256+
257+
### File: `docs/hooks/overview.md`
258+
259+
**Line ~97-98 - Go example uses wrong NewClient signature:**
260+
```go
261+
// Current (wrong):
262+
client, _ := copilot.NewClient(copilot.ClientOptions{})
263+
session, _ := client.CreateSession(ctx, copilot.SessionConfig{
264+
265+
// Should be:
266+
client := copilot.NewClient(nil)
267+
session, err := client.CreateSession(context.Background(), &copilot.SessionConfig{
268+
```
269+
270+
### File: `docs/debugging.md`
271+
272+
**Line ~50-52 - Go example returns error from NewClient:**
273+
```go
274+
// Current (wrong):
275+
client, err := copilot.NewClient(copilot.ClientOptions{
276+
LogLevel: "debug",
277+
})
278+
279+
// Should be:
280+
client := copilot.NewClient(&copilot.ClientOptions{
281+
LogLevel: "debug",
282+
})
283+
```
284+
285+
### File: `docs/guides/session-persistence.md`
286+
287+
**Lines ~67-80 - Go example uses wrong struct and method names:**
288+
```go
289+
// Current (wrong):
290+
client, _ := copilot.NewClient()
291+
session, _ := client.CreateSession(copilot.CreateSessionOptions{
292+
SessionID: "user-123-task-456",
293+
Model: "gpt-5.2-codex",
294+
})
295+
session.SendPrompt(copilot.PromptOptions{Content: "..."})
296+
297+
// Should be:
298+
client := copilot.NewClient(nil)
299+
if err := client.Start(); err != nil { ... }
300+
session, err := client.CreateSession(context.Background(), &copilot.SessionConfig{
301+
SessionID: "user-123-task-456",
302+
Model: "gpt-5.2-codex",
303+
})
304+
session.SendAndWait(copilot.MessageOptions{Prompt: "..."}, 0)
305+
```
306+
307+
---
308+
309+
## Broken Links
310+
311+
| Source File | Line | Broken Link | Suggested Fix |
312+
|-------------|------|-------------|---------------|
313+
| `docs/getting-started.md` | ~1023 | `./mcp.md` | Change to `./mcp/overview.md` |
314+
315+
---
316+
317+
## Consistency Issues
318+
319+
- [ ] Go examples inconsistently use `ctx` vs `context.Background()` - standardize on showing full import
320+
- [ ] Some Go examples show error handling, others use `_` - be consistent about error handling patterns
321+
- [ ] Python examples inconsistently use dict vs TypedDict for config - clarify which is preferred
322+
323+
---
324+
325+
## Validation Notes
326+
327+
The following were verified correct:
328+
- ✅ Node.js/TypeScript examples use correct `createSession`, `sendAndWait`, `defineTool` APIs
329+
- ✅ Python examples correctly use snake_case (`create_session`, `send_and_wait`)
330+
- ✅ .NET examples correctly use PascalCase (`CreateSessionAsync`, `SendAndWaitAsync`)
331+
- ✅ Hook names match SDK types (`onPreToolUse`, `on_pre_tool_use`, `OnPreToolUse`)
332+
- ✅ MCP server config structure is accurate across all languages
333+
- ✅ Provider config for BYOK is accurate
334+
- ✅ All languages show correct client initialization patterns (except Go errors noted above)

0 commit comments

Comments
 (0)