Skip to content

Commit bda8e26

Browse files
krukowkrukow
committed
Reorganize documentation and scripts
1 parent 9fdbb97 commit bda8e26

File tree

14 files changed

+682
-271
lines changed

14 files changed

+682
-271
lines changed

‎.github/copilot-instructions.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
../AGENTS.md

‎.github/skills/update-docs/SKILL.md‎

Lines changed: 230 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,230 @@
1+
---
2+
name: update-docs
3+
description: Update SDK documentation by analyzing source code changes and regenerating affected doc pages. Use when new features are added, APIs change, or docs need refresh.
4+
allowed-tools: View, Grep, Glob, Edit, Create, Task, Bash
5+
user-invocable: true
6+
---
7+
8+
# SDK Documentation Update Skill
9+
10+
You are updating the documentation for the copilot-sdk-clojure project. Your goal is to keep docs accurate, comprehensive, and aligned with the source code.
11+
12+
## Style Guide
13+
14+
**CRITICAL**: Before writing any documentation, read the full style guide at `doc/style.md`.
15+
16+
Key principles:
17+
18+
1. **Code-first** — Lead with working Clojure examples, then explain
19+
2. **Progressive disclosure** — Simplest usage first, layer complexity
20+
3. **Direct tone** — Imperative mood, no filler ("simply", "just", "let's")
21+
4. **Clojure-idiomatic** — Use Clojure terminology (namespaces, vars, maps, keywords)
22+
23+
Every doc must pass the checklist in `doc/style.md` before completion.
24+
25+
## Documentation Structure
26+
27+
```
28+
doc/
29+
├── index.md # Doc hub / navigation
30+
├── getting-started.md # Step-by-step tutorial
31+
├── style.md # Authoring conventions
32+
├── guides/ # Topic guides
33+
├── reference/
34+
│ └── API.md # Complete API reference
35+
├── auth/
36+
│ ├── index.md # Authentication overview
37+
│ └── byok.md # Bring Your Own Key guide
38+
├── mcp/
39+
│ ├── overview.md # MCP server integration
40+
│ └── debugging.md # MCP troubleshooting
41+
└── api/ # Auto-generated Codox HTML
42+
```
43+
44+
## Source Code → Documentation Mapping
45+
46+
| Doc Area | Primary Sources | Affected Docs |
47+
|----------|----------------|---------------|
48+
| Helpers API | `src/krukow/copilot_sdk/helpers.clj` | `doc/reference/API.md` (Helpers section), `doc/getting-started.md` |
49+
| Client API | `src/krukow/copilot_sdk/client.clj` | `doc/reference/API.md` (Client section) |
50+
| Session API | `src/krukow/copilot_sdk/session.clj` | `doc/reference/API.md` (Session section) |
51+
| Tools | `src/krukow/copilot_sdk/client.clj` (`define-tool`, `result-success`) | `doc/reference/API.md` (Tools section) |
52+
| Specs | `src/krukow/copilot_sdk/specs.clj`, `src/krukow/copilot_sdk/instrument.clj` | `doc/reference/API.md` |
53+
| MCP | `src/krukow/copilot_sdk/util.clj` (`mcp-server->wire`), `src/krukow/copilot_sdk/client.clj` | `doc/mcp/overview.md`, `doc/mcp/debugging.md` |
54+
| Auth/BYOK | `src/krukow/copilot_sdk/client.clj` (`:provider` in `create-session`) | `doc/auth/index.md`, `doc/auth/byok.md` |
55+
| Events | `src/krukow/copilot_sdk/client.clj` (`event-types`, `subscribe-events!`) | `doc/reference/API.md` (Events section) |
56+
| Examples | `examples/*.clj` | `examples/README.md`, related doc pages |
57+
58+
## Update Workflow
59+
60+
### 1. Identify Scope
61+
62+
If the user specifies a scope (e.g., "update mcp docs"), focus on that area only.
63+
64+
If no scope is specified, scan for changes:
65+
66+
```bash
67+
git diff --name-only HEAD~10 -- src/ examples/
68+
```
69+
70+
Map changed files to affected docs using the source mapping table above.
71+
72+
### 2. Analyze Source Code
73+
74+
For each affected area, use the `explore` agent to gather information:
75+
76+
```
77+
task agent_type: explore
78+
prompt: "In /path/to/repo, find all public functions in src/krukow/copilot_sdk/helpers.clj. List function name, arglists, and docstring."
79+
```
80+
81+
Key things to check in source:
82+
- Public function signatures (`defn`, `defmacro` — skip `defn-` private fns)
83+
- Docstrings
84+
- Spec definitions in `specs.clj` (option keys, types, defaults)
85+
- Default values and option maps
86+
- Event type constants
87+
88+
### 3. Generate/Update Documentation in Parallel
89+
90+
**IMPORTANT**: When multiple doc files need updates, use parallel `general-purpose` subagents via the `task` tool.
91+
92+
For each doc file that needs updating, launch a subagent:
93+
94+
```
95+
task agent_type: general-purpose
96+
prompt: |
97+
You are updating Clojure SDK documentation.
98+
99+
**STYLE GUIDE**: Read and follow doc/style.md strictly:
100+
- Lead with working Clojure code examples
101+
- Short paragraphs (1-3 sentences max)
102+
- Use tables for options/config keys
103+
- Use imperative mood
104+
- Show require forms in code blocks
105+
- Use ;; => for return values
106+
107+
**YOUR TASK**: Update doc/reference/API.md — Helpers API section
108+
109+
**RESEARCH**: Analyze src/krukow/copilot_sdk/helpers.clj for:
110+
- All public functions, their arglists, and docstrings
111+
- Option keys accepted (check specs.clj for spec definitions)
112+
- Return types and behavior
113+
114+
**REQUIREMENTS**:
115+
- Update function signatures if changed
116+
- Add any new functions
117+
- Ensure code examples match current API
118+
- Use relative links for cross-references
119+
```
120+
121+
### 4. Update Examples README
122+
123+
If examples changed, also update `examples/README.md`:
124+
- Verify all listed examples still exist as files
125+
- Update walkthroughs for changed examples
126+
- Add entries for new examples
127+
128+
### 5. Quality Gate
129+
130+
After all updates, run validation:
131+
132+
```bash
133+
bb validate-docs
134+
```
135+
136+
Fix any errors (broken links, unparseable code blocks) before finishing.
137+
138+
Also verify:
139+
- [ ] Code examples use correct `require` aliases (`copilot`, `h`, `session`)
140+
- [ ] Tables have consistent formatting
141+
- [ ] Cross-references use relative paths
142+
- [ ] No filler language
143+
- [ ] `doc/index.md` links are up to date
144+
145+
## Common Tasks
146+
147+
### New Public Function Added
148+
149+
1. Read the function from its source file
150+
2. Add to the appropriate section in `doc/reference/API.md`
151+
3. Include signature, description, options table, and example
152+
4. If it's a major feature, consider updating `doc/getting-started.md`
153+
154+
### New Example Added
155+
156+
1. Add entry to the examples table in `README.md`
157+
2. Add detailed walkthrough to `examples/README.md`
158+
3. Include difficulty level, concepts covered, and usage command
159+
160+
### New Config/Session Option
161+
162+
1. Read from `specs.clj` and `client.clj`
163+
2. Add to the session options table in `doc/reference/API.md`
164+
3. Add example usage if behavior is non-obvious
165+
166+
### Auth/BYOK Changes
167+
168+
1. Read from `client.clj` (create-session provider handling)
169+
2. Update `doc/auth/index.md` and/or `doc/auth/byok.md`
170+
3. Verify example provider configs still work
171+
172+
### MCP Changes
173+
174+
1. Read from `util.clj` (mcp-server->wire) and `client.clj`
175+
2. Update `doc/mcp/overview.md`
176+
3. Update `doc/mcp/debugging.md` if error handling changed
177+
178+
## Arguments
179+
180+
$ARGUMENTS
181+
182+
### Usage Modes
183+
184+
**Mode 1: Full docs refresh (default)**
185+
186+
```
187+
/update-docs
188+
/update-docs all
189+
```
190+
191+
Compares all source files against all docs. Updates everything out of sync.
192+
193+
**Mode 2: Specific section**
194+
195+
```
196+
/update-docs helpers
197+
/update-docs mcp
198+
/update-docs auth
199+
/update-docs getting-started
200+
```
201+
202+
Only updates docs for the specified area. Valid: `helpers`, `client`, `session`, `tools`, `events`, `mcp`, `auth`, `getting-started`, `examples`.
203+
204+
**Mode 3: Branch delta**
205+
206+
```
207+
/update-docs branch
208+
```
209+
210+
Compares your branch against `main`, identifies changed source files, and updates only affected docs.
211+
212+
### Mode Detection
213+
214+
Parse `$ARGUMENTS` to determine mode:
215+
216+
1. If arguments contain `branch`: Use Mode 3 (branch delta)
217+
2. If arguments contain a section name: Use Mode 2 (specific section)
218+
3. If arguments are empty or `all`: Use Mode 1 (full refresh)
219+
220+
### Branch Delta Workflow (Mode 3)
221+
222+
```bash
223+
# Get changed source files vs main
224+
git diff --name-only main...HEAD -- src/ examples/
225+
226+
# Map to affected docs using source mapping table
227+
# Launch parallel subagents for each affected doc
228+
```
229+
230+
Example: If `src/krukow/copilot_sdk/helpers.clj` changed, update `doc/reference/API.md` (Helpers section) and `doc/getting-started.md`.

‎.github/workflows/validate-docs.yml‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
name: Validate Documentation
2+
3+
on:
4+
pull_request:
5+
paths:
6+
- 'doc/**'
7+
- 'README.md'
8+
- 'AGENTS.md'
9+
- 'examples/**/*.md'
10+
- 'src/**'
11+
- 'script/validate_docs.clj'
12+
13+
jobs:
14+
validate-docs:
15+
runs-on: ubuntu-latest
16+
steps:
17+
- uses: actions/checkout@v4
18+
19+
- name: Install Babashka
20+
uses: DeLaGuardo/setup-graalvm@master
21+
with:
22+
graalvm-version: 'latest'
23+
- uses: turtlequeue/setup-babashka@v1.7.0
24+
with:
25+
babashka-version: '1.12.196'
26+
27+
- name: Validate documentation
28+
run: bb validate-docs

‎AGENTS.md‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -160,11 +160,16 @@ src/krukow/copilot_sdk/
160160
All these must be updated as appropriate when making changes:
161161

162162
- `README.md` - User-facing documentation and quick start
163-
- `doc/API.md` - Detailed API reference - read this to understand the current API design
163+
- `doc/index.md` - Documentation hub / table of contents
164+
- `doc/reference/API.md` - Detailed API reference - read this to understand the current API design
164165
- `doc/getting-started.md` - Step-by-step tutorial for new users
166+
- `doc/style.md` - Documentation authoring style guide
165167
- `doc/auth/index.md` - Authentication guide (all methods, priority order)
166168
- `doc/auth/byok.md` - BYOK (Bring Your Own Key) provider guide
167169
- `doc/mcp/overview.md` - MCP server configuration guide
168170
- `doc/mcp/debugging.md` - MCP debugging and troubleshooting
169171
- `CHANGELOG.md` - Version history and changes
170172
- `AGENTS.md` - update this file when significant changes happen (e.g.Project Structure)
173+
174+
Run `bb validate-docs` to check for broken links, unparseable code blocks, and structural issues.
175+
Use `/update-docs` skill (`.github/skills/update-docs/SKILL.md`) to regenerate docs after source changes.

‎README.md‎

Lines changed: 1 addition & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -99,7 +99,7 @@ See [`examples/`](./examples/) for more patterns including streaming, custom too
9999

100100
## API Reference
101101

102-
See [doc/API.md](./doc/API.md) for the complete API reference, including:
102+
See [doc/reference/API.md](./doc/reference/API.md) for the complete API reference, including:
103103

104104
- **CopilotClient** - Client options, lifecycle methods (`start!`, `stop!`, `with-client`)
105105
- **CopilotSession** - Session methods (`send!`, `send-and-wait!`, `<send!`, `events`)
@@ -116,7 +116,6 @@ See the [`examples/`](./examples/) directory for complete working examples:
116116
| [`basic_chat.clj`](./examples/basic_chat.clj) | Beginner | Simple Q&A conversation with multi-turn context |
117117
| [`tool_integration.clj`](./examples/tool_integration.clj) | Intermediate | Custom tools that the LLM can invoke |
118118
| [`multi_agent.clj`](./examples/multi_agent.clj) | Advanced | Multi-agent orchestration with core.async |
119-
| [`streaming_chat.clj`](./examples/streaming_chat.clj) | Intermediate | Streaming deltas with incremental output |
120119
| [`config_skill_output.clj`](./examples/config_skill_output.clj) | Intermediate | Config dir, skills, and large output settings |
121120
| [`permission_bash.clj`](./examples/permission_bash.clj) | Intermediate | Permission handling with bash |
122121

@@ -126,7 +125,6 @@ Run examples:
126125
clojure -A:examples -M -m basic-chat
127126
clojure -A:examples -M -m tool-integration
128127
clojure -A:examples -M -m multi-agent
129-
clojure -A:examples -M -m streaming-chat
130128
clojure -A:examples -M -m config-skill-output
131129
clojure -A:examples -M -m permission-bash
132130
```

‎bb.edn‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -38,4 +38,7 @@
3838
:task (clojure "-T:build" "deploy-central")}
3939

4040
install {:doc "Install the JAR locally (build via ci)."
41-
:task (clojure "-T:build" "install")}}}
41+
:task (clojure "-T:build" "install")}
42+
43+
validate-docs {:doc "Validate documentation: links, code blocks, and structure."
44+
:task (shell "bb" "script/validate_docs.clj")}}}

‎doc/getting-started.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -206,7 +206,7 @@ Let's put it all together into an interactive assistant:
206206

207207
Now that you have the basics, explore these topics:
208208

209-
- **[API Reference](./API.md)** — Complete API documentation
209+
- **[API Reference](./reference/API.md)** — Complete API documentation
210210
- **[Authentication](./auth/index.md)** — All auth methods including BYOK
211211
- **[MCP Servers](./mcp/overview.md)** — Connect to external tools via MCP
212212
- **[Examples](../examples/README.md)** — More working examples

‎doc/index.md‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
# Documentation
2+
3+
Clojure SDK for programmatic control of the GitHub Copilot CLI via JSON-RPC.
4+
5+
## Getting Started
6+
7+
- [Getting Started](getting-started.md) — Step-by-step tutorial building a weather assistant
8+
- [Examples](../examples/README.md) — 11 working examples with walkthroughs
9+
10+
## Guides
11+
12+
- [Authentication](auth/index.md) — GitHub auth, OAuth, environment variables, priority order
13+
- [BYOK Providers](auth/byok.md) — Bring Your Own Key for OpenAI, Azure, Anthropic, Ollama
14+
- [MCP Servers](mcp/overview.md) — Model Context Protocol server integration
15+
- [MCP Debugging](mcp/debugging.md) — Troubleshooting MCP connections
16+
17+
## Reference
18+
19+
- [API Reference](reference/API.md) — Complete API: helpers, client, session, events, tools
20+
- [Generated API Docs](api/index.html) — Codox-generated namespace documentation
21+
22+
## Contributing
23+
24+
- [Style Guide](style.md) — Documentation authoring conventions
25+
- [AGENTS.md](../AGENTS.md) — Guidelines for AI agents working on this codebase
26+
- [CHANGELOG](../CHANGELOG.md) — Version history

0 commit comments

Comments
 (0)