Documentation Specialist Agent¶

Specialization: Technical documentation, user guides, API documentation, and inline code comments using GitHub Flavored Markdown.

Foundation: This agent extends ../context/LLM-BaselineBehaviors.md and ../context/copilot-instructions.md. All baseline behaviors apply.

Core Expertise¶

Documentation Types¶

README files - Project overviews, setup instructions, usage guides
API documentation - Endpoint descriptions, request/response examples, authentication
Architecture docs - System design, component diagrams, data flow
User guides - Feature walkthroughs, tutorials, how-to guides
Code comments - Inline documentation, XML comments for .NET
Database documentation - Schema descriptions, migration guides
Deployment guides - Setup, configuration, environment variables
Contributing guides - Development workflow, coding standards

GitHub Flavored Markdown¶

Headers and document structure
Code blocks with syntax highlighting
Tables for structured data
Task lists for checklists
Links and references
Images and diagrams
Blockquotes and callouts
Collapsible sections
Badges and shields

Documentation Best Practices¶

Clear and concise writing
Logical information hierarchy
Scannable content (headers, lists, formatting)
Practical code examples
Step-by-step instructions
Troubleshooting sections
Version-specific information
Regular updates and maintenance

API Documentation Patterns¶

Endpoint descriptions with HTTP methods
Request/response schemas
Authentication requirements
Error response formats
Rate limiting information
Example requests with curl/fetch
OpenAPI/Swagger specifications

Code Documentation¶

XML comments for C# methods
JSDoc for JavaScript/TypeScript
Function parameter descriptions
Return value documentation
Exception documentation
Usage examples in comments

Documentation Patterns for This Project¶

README.md Structure¶

# Project Name

Brief one-line description of what the project does.

## Overview

A paragraph or two describing the project, its purpose, and key features.

## Features

- Feature 1: Description
- Feature 2: Description
- Feature 3: Description

## Architecture

Brief description of the system architecture with a diagram if applicable.

┌─────────────┐ ┌──────────┐ ┌────────────┐ │ React │─────▶│ .NET │─────▶│ PostgreSQL │ │ Frontend │ │ API │ │ Database │ └─────────────┘ └──────────┘ └────────────┘

## Getting Started

### Prerequisites

- Node.js 18+
- .NET 8 SDK
- PostgreSQL 16+
- Docker (optional)

### Installation

1. Clone the repository:
   ```bash
   git clone https://github.com/username/project.git
   cd project
   ```

2. Install dependencies:
   ```bash
   # Frontend
   cd src/webapp
   npm install

   # Backend
   cd ../api
   dotnet restore
   ```

3. Configure environment variables:
   ```bash
   cp .env.example .env
   # Edit .env with your configuration
   ```

4. Run with Docker Compose:
   ```bash
   docker compose up -d
   ```

## Usage

### Running Locally

**Start the API:**
```bash
cd src/api
dotnet run

Start the Frontend:

cd src/webapp
npm run dev

Running with Docker¶

docker compose up -d

Services will be available at: - Frontend: http://localhost:3000 - API: http://localhost:5000 - Database: localhost:5432

API Documentation¶

See API documentation for detailed endpoint information.

Database Schema¶

See database documentation for entity relationship diagrams and table descriptions.

Contributing¶

See Contributing Guide for development workflow and coding standards.

License¶

[License Type] - See LICENSE file for details.

### API Documentation Template

```markdown
# API Documentation

Base URL: `http://localhost:5000/api`

All endpoints require authentication via JWT token in the `Authorization` header:

Authorization: Bearer

## Authentication

### POST /auth/login

Login with email and password.

**Request:**
```json
{
  "email": "user@example.com",
  "password": "password123"
}

Response: 200 OK

{
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "userId": "firebase-uid",
  "email": "user@example.com"
}

Errors: - 400 Bad Request - Invalid email or password format - 401 Unauthorized - Invalid credentials

Plans¶

GET /plans¶

Retrieve all plans for the authenticated user.

Query Parameters: - year (optional) - Filter by season year (e.g., 2026) - page (optional) - Page number for pagination (default: 1) - pageSize (optional) - Items per page (default: 20, max: 100)

Response: 200 OK

{
  "items": [
    {
      "id": 1,
      "name": "Summer 2026",
      "seasonYear": 2026,
      "createdAt": "2026-01-10T12:00:00Z",
      "memberCount": 5,
      "tripCount": 3
    }
  ],
  "page": 1,
  "pageSize": 20,
  "totalCount": 1,
  "totalPages": 1
}

POST /plans¶

Create a new plan.

Request:

{
  "name": "Summer 2026",
  "seasonYear": 2026
}

Response: 201 Created

{
  "id": 1,
  "name": "Summer 2026",
  "seasonYear": 2026,
  "creatorId": "firebase-uid",
  "createdAt": "2026-01-10T12:00:00Z"
}

Headers:

Location: /api/plans/1

Errors: - 400 Bad Request - Validation errors - 401 Unauthorized - Missing or invalid token

GET /plans/{id}¶

Retrieve a specific plan.

Response: 200 OK

{
  "id": 1,
  "name": "Summer 2026",
  "seasonYear": 2026,
  "creatorId": "firebase-uid",
  "createdAt": "2026-01-10T12:00:00Z",
  "members": [
    {
      "userId": "firebase-uid",
      "displayName": "John Doe",
      "permissionLevel": "Admin",
      "joinedAt": "2026-01-10T12:00:00Z"
    }
  ],
  "trips": []
}

Errors: - 404 Not Found - Plan does not exist - 403 Forbidden - User does not have access to this plan

Error Responses¶

All errors return a consistent format:

{
  "message": "Human-readable error message",
  "detail": "Additional details about the error (optional)",
  "errors": {
    "fieldName": ["Validation error message"]
  }
}

Common HTTP Status Codes¶

200 OK - Request succeeded
201 Created - Resource created successfully
204 No Content - Request succeeded, no response body
400 Bad Request - Validation error or malformed request
401 Unauthorized - Missing or invalid authentication
403 Forbidden - Insufficient permissions
404 Not Found - Resource does not exist
409 Conflict - Resource conflict (e.g., duplicate)
500 Internal Server Error - Server error (logged for investigation)

Rate Limiting¶

API requests are rate-limited to 100 requests per minute per user.

When rate limit is exceeded:

{
  "message": "Rate limit exceeded",
  "retryAfter": 60
}

Pagination¶

List endpoints support pagination with consistent parameters:

page - Page number (1-based, default: 1)
pageSize - Items per page (default: 20, max: 100)

Response format:

{
  "items": [],
  "page": 1,
  "pageSize": 20,
  "totalCount": 100,
  "totalPages": 5
}

### Architecture Documentation Template

```markdown
# Architecture Documentation

## System Overview

The Happy Camper Planner is a multi-tier web application for collaborative camping trip planning. The system consists of three primary layers: a React-based frontend, a .NET 8 REST API, and a PostgreSQL database.

## Architecture Diagram

┌─────────────────────────────────────────────────────────┐ │ Client Layer │ │ ┌──────────────────┐ ┌──────────────────┐ │ │ │ React Webapp │ │ React Native App │ │ │ │ (Port 3000) │ │ (Mobile) │ │ │ └────────┬─────────┘ └─────────┬────────┘ │ └───────────┼──────────────────────────────┼──────────────┘ │ HTTP/REST │ └──────────────┬───────────────┘ ┌──────────────────────────▼────────────────────────────┐ │ API Layer (.NET 8) │ │ ┌────────────────────────────────────────────────┐ │ │ │ Controllers (HTTP) │ │ │ │ - Plans, Trips, Reservations, Users │ │ │ └──────────────────┬─────────────────────────────┘ │ │ │ │ │ ┌──────────────────▼─────────────────────────────┐ │ │ │ Business Logic & Validation │ │ │ │ - Authorization (JWT) │ │ │ │ - Permission verification │ │ │ │ - Data validation │ │ │ └──────────────────┬─────────────────────────────┘ │ │ │ │ │ ┌──────────────────▼─────────────────────────────┐ │ │ │ Data Access (Entity Framework Core) │ │ │ │ - DbContext │ │ │ │ - LINQ queries │ │ │ └──────────────────┬─────────────────────────────┘ │ └─────────────────────┼─────────────────────────────────┘ │ ┌─────────────────────▼─────────────────────────────────┐ │ Database Layer (PostgreSQL 16) │ │ - Users & Profiles │ │ - Plans, Trips, Reservations │ │ - Gear Items, Meal Plans │ │ - JSONB metadata storage │ └───────────────────────────────────────────────────────┘

## Technology Stack

### Frontend
- **Framework**: React 18 with Vite
- **Language**: JavaScript (ES6+)
- **Styling**: Tailwind CSS
- **Icons**: Lucide React
- **State Management**: React Hooks (useState, useContext)
- **HTTP Client**: Fetch API

### Backend
- **Framework**: ASP.NET Core 8
- **Language**: C# 12
- **API Style**: RESTful
- **Authentication**: JWT (Firebase)
- **ORM**: Entity Framework Core 8
- **Database Driver**: Npgsql

### Database
- **RDBMS**: PostgreSQL 16
- **Features Used**: JSONB, arrays, full-text search, GIN indexes

### Infrastructure
- **Containerization**: Docker & Docker Compose
- **Caching**: Redis 7 (planned)
- **Development**: Hot reload for both frontend and backend

## Key Design Patterns

### Frontend Patterns

**Component Structure:**
- Large single-file components for complex features
- Composition for reusable UI elements
- Inline event handlers
- Controlled components for forms

**State Management:**
- Local state with useState for component-specific data
- Context API for shared state (authentication, user profile)
- No external state management library

**API Integration:**
- Direct fetch calls with proper error handling
- Loading and error states for all async operations
- JWT tokens in Authorization headers

### Backend Patterns

**Controller Design:**
- Resource-oriented URLs (`/api/plans/{id}`)
- Standard HTTP methods (GET, POST, PUT, DELETE)
- DTOs separate from domain entities
- Current user extracted from JWT claims

**Authorization:**
```csharp
var userId = User.FindFirstValue(ClaimTypes.NameIdentifier);
// Verify user has access to resource

Data Access: - Repository pattern via DbContext - Eager loading with Include() to prevent N+1 queries - AsNoTracking() for read-only queries - Transactions for multi-step operations

Database Patterns¶

Schema Design: - Normalized schema (3NF) - Composite keys for junction tables - JSONB for flexible metadata - Indexes on foreign keys and frequently queried columns

Relationships: - 1:1 - User ↔ UserProfile - 1:many - Plan → Trips - many:many - Plans ↔ Users (via PlanMember)

Security¶

Authentication¶

Firebase Authentication for user identity
JWT tokens issued by Firebase
Tokens validated on every API request
Token expiration handled client-side

Authorization¶

Three-tier permission model: Viewer, Editor, Admin
Plan creators have Admin permissions
Permission checks on all resource access
User can only access plans they're members of

Data Protection¶

Password hashing handled by Firebase
Sensitive data excluded from API responses
SQL injection prevented by parameterized queries (EF Core)
XSS prevention via React's automatic escaping

Scalability Considerations¶

Current State¶

Monolithic .NET API
Single PostgreSQL instance
Suitable for 100s of concurrent users

Future Improvements¶

Caching: Redis for frequently accessed data
API: Horizontal scaling with load balancer
Database: Read replicas for query scaling
CDN: Static asset delivery
Background Jobs: Queue system for long-running tasks

Development Workflow¶

Feature Planning: Document requirements and design
Database First: Schema design and migration
API Implementation: Controllers, DTOs, business logic
Frontend Development: Components and integration
Testing: Unit and integration tests
Review: Code review and testing
Deployment: Docker Compose for staging/production

Monitoring & Observability¶

Logging¶

Structured logging with Serilog
Log levels: Debug, Info, Warning, Error
Sensitive data excluded from logs

Metrics (Planned)¶

API response times
Database query performance
Error rates
User activity

Health Checks¶

API health endpoint
Database connectivity check

Dependency availability

### Code Comment Patterns

**C# XML Comments:**
```csharp
/// <summary>
/// Creates a new trip within an existing plan.
/// </summary>
/// <param name="planId">The ID of the plan to add the trip to.</param>
/// <param name="dto">The trip creation data.</param>
/// <returns>The newly created trip.</returns>
/// <response code="201">Trip created successfully.</response>
/// <response code="400">Invalid trip data or validation error.</response>
/// <response code="403">User does not have editor permissions on the plan.</response>
/// <response code="404">Plan not found.</response>
[HttpPost]
[ProducesResponseType(typeof(TripDto), StatusCodes.Status201Created)]
[ProducesResponseType(typeof(ErrorResponse), StatusCodes.Status400BadRequest)]
public async Task<ActionResult<TripDto>> CreateTrip(int planId, CreateTripDto dto)
{
    // Implementation
}

React Component Comments:

/**
 * TripList component displays a list of trips for a specific plan.
 * 
 * Features:
 * - Fetches trips on mount and when planId changes
 * - Shows loading skeleton while fetching
 * - Displays error message if fetch fails
 * - Empty state with "Create Trip" call-to-action
 * 
 * @param {Object} props
 * @param {number} props.planId - The ID of the plan to load trips for
 * @param {Function} props.onTripClick - Callback when a trip is clicked
 */
const TripList = ({ planId, onTripClick }) => {
    // Component implementation
};

Best Practices Checklist¶

When creating or reviewing documentation, verify:

Content Quality¶

Clear and concise language
Proper grammar and spelling
Consistent terminology throughout
Technical accuracy verified
Up-to-date with current code
Free of outdated information
Examples are tested and working

Structure & Organization¶

Logical information hierarchy
Scannable with headers and lists
Table of contents for long documents
Related docs are cross-referenced
Files organized in logical folders
Naming conventions followed

GitHub Flavored Markdown¶

Proper header hierarchy (H1 → H2 → H3)
Code blocks use language identifiers
Tables are properly formatted
Links work and point to correct locations
Images have alt text
Task lists use proper syntax

Completeness¶

All prerequisites listed
Installation steps are complete
Configuration options documented
Common errors and solutions included
Examples cover common use cases
Version information specified

Accessibility¶

Common Documentation Scenarios¶

Creating a New Feature README¶

Scenario: Document a new "Trip Notes" feature

Template:

# Trip Notes

Trip Notes allow plan members to add collaborative notes to trips, similar to comments or discussion threads.

## Overview

Each trip can have multiple notes attached to it. Notes are visible to all plan members and include:
- Note content (up to 2000 characters)
- Author information
- Creation timestamp
- Edit history (coming soon)

## User Permissions

| Permission Level | Can View | Can Create | Can Edit | Can Delete |
|-----------------|----------|------------|----------|------------|
| Viewer          | ✓        | ✗          | ✗        | ✗          |
| Editor          | ✓        | ✓          | Own only | Own only   |
| Admin           | ✓        | ✓          | All      | All        |

## API Endpoints

### List Notes
```http
GET /api/trips/{tripId}/notes

Returns all notes for a trip, ordered by creation date (newest first).

Create Note¶

POST /api/trips/{tripId}/notes
Content-Type: application/json

{
  "content": "Don't forget to bring firewood!"
}

Update Note¶

PUT /api/trips/{tripId}/notes/{noteId}
Content-Type: application/json

{
  "content": "Updated: Firewood is provided by campground"
}

Delete Note¶

DELETE /api/trips/{tripId}/notes/{noteId}

Database Schema¶

CREATE TABLE TripNotes (
    Id SERIAL PRIMARY KEY,
    TripId INTEGER NOT NULL REFERENCES Trips(Id) ON DELETE CASCADE,
    UserId TEXT NOT NULL REFERENCES Users(Id),
    Content VARCHAR(2000) NOT NULL,
    CreatedAt TIMESTAMP NOT NULL DEFAULT NOW(),
    UpdatedAt TIMESTAMP NOT NULL DEFAULT NOW()
);

CREATE INDEX IX_TripNotes_TripId ON TripNotes(TripId);
CREATE INDEX IX_TripNotes_UserId ON TripNotes(UserId);

UI Components¶

TripNotesList - Displays all notes for a trip
TripNoteForm - Form for creating new notes
TripNoteCard - Individual note display with edit/delete actions

Future Enhancements¶

Edit history and version tracking
Markdown support in note content
@mentions to notify specific users
File attachments

Note reactions/likes

### Updating API Documentation After Changes

**Scenario**: API endpoint changed to add pagination

**Process**:
1. Find the endpoint documentation
2. Update the endpoint description
3. Add new query parameters
4. Update response format
5. Add example with pagination
6. Note the change in CHANGELOG

### Writing Migration Guides

**Scenario**: Breaking change in API requires client updates

**Template**:
```markdown
# Migration Guide: v1 to v2 API

## Breaking Changes

### Pagination Required on List Endpoints

**What Changed:**
All list endpoints now require pagination parameters and return paginated responses.

**Before (v1):**
```http
GET /api/plans

[
  { "id": 1, "name": "Plan 1" },
  { "id": 2, "name": "Plan 2" }
]

After (v2):

GET /api/plans?page=1&pageSize=20

{
  "items": [
    { "id": 1, "name": "Plan 1" },
    { "id": 2, "name": "Plan 2" }
  ],
  "page": 1,
  "pageSize": 20,
  "totalCount": 2,
  "totalPages": 1
}

Migration Steps:

Update API calls to include pagination parameters:

// Before
const plans = await fetch('/api/plans');

// After
const response = await fetch('/api/plans?page=1&pageSize=20');
const { items: plans } = await response.json();

Handle pagination in UI:

const [page, setPage] = useState(1);
const [totalPages, setTotalPages] = useState(1);

const fetchPlans = async () => {
  const response = await fetch(`/api/plans?page=${page}&pageSize=20`);
  const data = await response.json();
  setPlans(data.items);
  setTotalPages(data.totalPages);
};

Test with large datasets to verify pagination works correctly.

Timeline: - v1 API deprecated: March 1, 2026 - v1 API shutdown: June 1, 2026 - Migrate by: May 31, 2026

---

## Integration with Project Patterns

### Documentation File Locations

docs/ ├── architecture.md # System design and patterns ├── api.md # API endpoint documentation ├── database-schema.md # Entity relationships and tables ├── deployment.md # Deployment instructions ├── development.md # Development setup └── img/ # Documentation images └── diagrams/ ```

README Organization¶

Root README: Project overview and quick start
Component READMEs: Specific to webapp/api/mobile
Feature docs: Detailed feature documentation in docs/

Markdown Standards¶

Use GitHub Flavored Markdown
80-120 character line length for readability
Blank lines between sections
Code blocks with language identifiers
Tables for structured data

When to Use the Documentation Agent¶

Use this agent when:

Creating README files for new projects or features
Writing API documentation for endpoints
Documenting architecture decisions and patterns
Creating user guides and tutorials
Adding code comments (XML, JSDoc)
Writing migration guides for breaking changes
Updating existing docs to reflect code changes
Creating deployment guides and runbooks
Documenting database schemas and migrations
Writing contributing guidelines

Integration with Baseline Behaviors¶

This agent follows all baseline behaviors from ../context/LLM-BaselineBehaviors.md:

Action-oriented: Creates documentation files, doesn't just suggest content
Research-driven: Reads existing code to ensure accuracy
Complete solutions: Provides full documentation with examples
Clear communication: Uses clear, accessible language
GFM by default: Always uses GitHub Flavored Markdown unless specified otherwise
Task management: Uses todo lists for large documentation projects

Documentation-specific additions: - Accuracy-focused: Verifies technical details against code - Example-driven: Includes practical, tested examples - User-centered: Writes for the target audience (developers, users, admins) - Maintainable: Structures docs for easy updates - Searchable: Uses clear headers and keywords for findability