update-docs

name	update-docs
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. Use when this capability is needed.
metadata	{"author":"copilot-community-sdk"}

SDK Documentation Update Skill

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.

Style Guide

CRITICAL: Before writing any documentation, read the full style guide at doc/style.md.

Key principles:

1. Code-first — Lead with working Clojure examples, then explain
2. Progressive disclosure — Simplest usage first, layer complexity
3. Direct tone — Imperative mood, no filler ("simply", "just", "let's")
4. Clojure-idiomatic — Use Clojure terminology (namespaces, vars, maps, keywords)

Every doc must pass the checklist in doc/style.md before completion.

Documentation Structure

doc/
├── index.md              # Doc hub / navigation
├── getting-started.md    # Step-by-step tutorial
├── style.md              # Authoring conventions
├── guides/               # Topic guides
├── reference/
│   └── API.md            # Complete API reference
├── auth/
│   ├── index.md          # Authentication overview
│   └── byok.md           # Bring Your Own Key guide
├── mcp/
│   ├── overview.md       # MCP server integration
│   └── debugging.md      # MCP troubleshooting
└── api/                  # Auto-generated Codox HTML

Source Code → Documentation Mapping

Doc Area	Primary Sources	Affected Docs
Helpers API	src/github/copilot_sdk/helpers.clj	doc/reference/API.md (Helpers section), doc/getting-started.md
Client API	src/github/copilot_sdk/client.clj	doc/reference/API.md (Client section)
Session API	src/github/copilot_sdk/session.clj	doc/reference/API.md (Session section)
Tools	src/github/copilot_sdk/client.clj (define-tool, result-success)	doc/reference/API.md (Tools section)
Specs	src/github/copilot_sdk/specs.clj, src/github/copilot_sdk/instrument.clj	doc/reference/API.md
MCP	src/github/copilot_sdk/util.clj (mcp-server->wire), src/github/copilot_sdk/client.clj	doc/mcp/overview.md, doc/mcp/debugging.md
Auth/BYOK	src/github/copilot_sdk/client.clj (:provider in create-session)	doc/auth/index.md, doc/auth/byok.md
Events	src/github/copilot_sdk/client.clj (event-types, subscribe-events!)	doc/reference/API.md (Events section)
Examples	examples/*.clj	examples/README.md, related doc pages

Update Workflow

1. Identify Scope

If the user specifies a scope (e.g., "update mcp docs"), focus on that area only.

If no scope is specified, scan for changes:

git diff --name-only HEAD~10 -- src/ examples/

Map changed files to affected docs using the source mapping table above.

2. Analyze Source Code

For each affected area, use the explore agent to gather information:

task agent_type: explore
prompt: "In /path/to/repo, find all public functions in src/github/copilot_sdk/helpers.clj. List function name, arglists, and docstring."

Key things to check in source:

• Public function signatures (defn, defmacro — skip defn- private fns)
• Docstrings
• Spec definitions in specs.clj (option keys, types, defaults)
• Default values and option maps
• Event type constants

3. Generate/Update Documentation in Parallel

IMPORTANT: When multiple doc files need updates, use parallel general-purpose subagents via the task tool.

For each doc file that needs updating, launch a subagent:

task agent_type: general-purpose
prompt: |
  You are updating Clojure SDK documentation.

  **STYLE GUIDE**: Read and follow doc/style.md strictly:
  - Lead with working Clojure code examples
  - Short paragraphs (1-3 sentences max)
  - Use tables for options/config keys
  - Use imperative mood
  - Show require forms in code blocks
  - Use ;; => for return values

  **YOUR TASK**: Update doc/reference/API.md — Helpers API section

  **RESEARCH**: Analyze src/github/copilot_sdk/helpers.clj for:
  - All public functions, their arglists, and docstrings
  - Option keys accepted (check specs.clj for spec definitions)
  - Return types and behavior

  **REQUIREMENTS**:
  - Update function signatures if changed
  - Add any new functions
  - Ensure code examples match current API
  - Use relative links for cross-references

4. Update Examples README

If examples changed, also update examples/README.md:

• Verify all listed examples still exist as files
• Update walkthroughs for changed examples
• Add entries for new examples

5. Regenerate Codox HTML

After updating source docstrings or markdown docs, regenerate the Codox API HTML:

bb docs          # or: clojure -X:codox

This regenerates doc/api/*.html from source docstrings. Always run this after changing docstrings in src/ so the HTML stays in sync with the source.

6. Quality Gate

After all updates, run validation:

bb validate-docs

Fix any errors (broken links, unparseable code blocks) before finishing.

Also verify:

• Code examples use correct require aliases (copilot, h, session)
• Tables have consistent formatting
• Cross-references use relative paths
• No filler language
• doc/index.md links are up to date
• doc/api/ HTML is regenerated if source docstrings changed

Common Tasks

New Public Function Added

1. Read the function from its source file
2. Add to the appropriate section in doc/reference/API.md
3. Include signature, description, options table, and example
4. If it's a major feature, consider updating doc/getting-started.md

New Example Added

1. Add entry to the examples table in README.md
2. Add detailed walkthrough to examples/README.md
3. Include difficulty level, concepts covered, and usage command

New Config/Session Option

1. Read from specs.clj and client.clj
2. Add to the session options table in doc/reference/API.md
3. Add example usage if behavior is non-obvious

Auth/BYOK Changes

1. Read from client.clj (create-session provider handling)
2. Update doc/auth/index.md and/or doc/auth/byok.md
3. Verify example provider configs still work

MCP Changes

1. Read from util.clj (mcp-server->wire) and client.clj
2. Update doc/mcp/overview.md
3. Update doc/mcp/debugging.md if error handling changed

Arguments

$ARGUMENTS

Usage Modes

Mode 1: Full docs refresh (default)

/update-docs
/update-docs all

Compares all source files against all docs. Updates everything out of sync.

Mode 2: Specific section

/update-docs helpers
/update-docs mcp
/update-docs auth
/update-docs getting-started

Only updates docs for the specified area. Valid: helpers, client, session, tools, events, mcp, auth, getting-started, examples.

Mode 3: Branch delta

/update-docs branch

Compares your branch against main, identifies changed source files, and updates only affected docs.

Mode Detection

Parse $ARGUMENTS to determine mode:

1. If arguments contain branch: Use Mode 3 (branch delta)
2. If arguments contain a section name: Use Mode 2 (specific section)
3. If arguments are empty or all: Use Mode 1 (full refresh)

Branch Delta Workflow (Mode 3)

# Get changed source files vs main
git diff --name-only main...HEAD -- src/ examples/

# Map to affected docs using source mapping table
# Launch parallel subagents for each affected doc

Example: If src/github/copilot_sdk/helpers.clj changed, update doc/reference/API.md (Helpers section) and doc/getting-started.md.

---

Converted and distributed by TomeVault — claim your Tome and manage your conversions.