docs: add documentation style guide for AI agents

Add comprehensive documentation style guide in .claude/docs/ directory
following the format established in PR #21148 for PR_STYLE_GUIDE.md.

This guide captures observed patterns from existing Coder documentation
including:

- Research requirements before writing (code verification, permissions,
  thresholds)
- Document structure and organization patterns
- Image usage and screenshot guidelines
- Writing style and terminology conventions
- Code examples and formatting standards
- Documentation manifest requirements
- Accuracy standards for specific numbers, permissions, and API endpoints
- Proactive documentation approach for upcoming features

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

.claude/docs/DOCS_STYLE_GUIDE.md

@@ -0,0 +1,299 @@
+# Documentation Style Guide
+
+This guide documents documentation patterns observed in the Coder repository, based on analysis of existing admin guides, tutorials, and reference documentation. This is specifically for documentation files in the `docs/` directory - see [CONTRIBUTING.md](../../docs/about/contributing/CONTRIBUTING.md) for general contribution guidelines.
+
+## Research Before Writing
+
+Before documenting a feature, verify implementation details against the actual codebase:
+
+1. **Read the code implementation** - Check backend endpoints, frontend components, database queries
+2. **Verify permissions model** - Look up RBAC actions in `coderd/rbac/` (e.g., `view_insights` for Template Insights)
+3. **Check UI thresholds and defaults** - Review frontend code for color thresholds, time intervals, display logic
+4. **Cross-reference with tests** - Test files document expected behavior and edge cases
+5. **Verify API endpoints** - Check `coderd/coderd.go` for route registration
+
+### Code Verification Checklist
+
+- Read handler implementation in `coderd/`
+- Check permission requirements in `coderd/rbac/`
+- Review frontend components in `site/src/pages/` or `site/src/modules/`
+- Verify display thresholds and intervals (e.g., color codes, time defaults)
+- Confirm API endpoint paths and parameters
+- Check for server flags in serpent configuration
+
+## Document Structure
+
+### Title and Introduction Pattern
+
+**H1 heading**: Single clear title without prefix
+
+```markdown
+# Template Insights
+```
+
+**Introduction**: 1-2 sentences describing what the feature does, concise and actionable
+
+```markdown
+Template Insights provides detailed analytics and usage metrics for your Coder templates.
+```
+
+### Premium Feature Callout
+
+Place immediately after title if feature requires Premium license:
+
+```markdown
+> [!NOTE]
+> Feature name is a Premium feature.
+> [Learn more](https://coder.com/pricing#compare-plans).
+```
+
+### Overview Section Pattern
+
+Common pattern after introduction:
+
+```markdown
+## Overview
+
+Template Insights offers visibility into:
+
+- **Active Users**: Track the number of users actively using workspaces
+- **Application Usage**: See which applications users are accessing
+```
+
+Use bold labels for capabilities, provides high-level understanding before details.
+
+## Image Usage
+
+### Placement and Format
+
+**Place images after descriptive text**, then add caption:
+
+```markdown
+![Template Insights page](../../images/admin/templates/template-insights.png)
+
+<small>Template Insights showing weekly active users and connection latency metrics.</small>
+```
+
+- Image format: `![Descriptive alt text](../../path/to/image.png)`
+- Caption: Use `<small>` tag below images
+- Alt text: Describe what's shown, not just repeat heading
+
+### Image-Driven Documentation
+
+When you have multiple screenshots showing different aspects of a feature:
+
+1. **Structure sections around images** - Each major screenshot gets its own section
+2. **Describe what's visible** - Reference specific UI elements, data values shown in the screenshot
+3. **Flow naturally** - Let screenshots guide the reader through the feature
+
+**Example**: Template Insights documentation has 3 screenshots that define the 3 main content sections.
+
+### Screenshot Guidelines
+
+- Illustrate features being discussed in preceding text
+- Show actual UI/data, not abstract concepts
+- Reference specific values shown when explaining features
+- Organize documentation around key screenshots
+
+## Content Organization
+
+### Section Hierarchy
+
+1. **H2 (##)**: Major sections - "Overview", "Accessing [Feature]", "Use Cases"
+2. **H3 (###)**: Subsections within major sections
+3. **H4 (####)**: Rare, only for deeply nested content
+
+### Common Section Patterns
+
+- **Accessing [Feature]**: How to navigate to/use the feature
+- **Use Cases**: Practical applications
+- **Permissions**: Access control information
+- **API Access**: Programmatic access details
+- **Related Documentation**: Links to related content
+
+### Lists and Callouts
+
+- **Unordered lists**: Non-sequential items, features, capabilities
+- **Ordered lists**: Step-by-step instructions
+- **Tables**: Comparing options, showing permissions, listing parameters
+- **Callouts**:
+  - `> [!NOTE]` for additional information
+  - `> [!WARNING]` for important warnings
+  - `> [!TIP]` for helpful tips
+
+## Writing Style
+
+### Tone and Voice
+
+- **Direct and concise**: Avoid unnecessary words
+- **Active voice**: "Template Insights tracks users" not "Users are tracked"
+- **Present tense**: "The chart displays..." not "The chart will display..."
+- **Second person**: "You can view..." for instructions
+
+### Terminology
+
+- **Consistent terms**: Use same term throughout (e.g., "workspace" not "workspace environment")
+- **Bold for UI elements**: "Navigate to the **Templates** page"
+- **Code formatting**: Use backticks for commands, file paths, code
+  - Inline: `` `coder server` ``
+  - Blocks: Use triple backticks with language identifier
+
+### Instructions
+
+- **Numbered lists** for sequential steps
+- **Start with verb**: "Navigate to", "Click", "Select", "Run"
+- **Be specific**: Include exact button/menu names in bold
+
+## Code Examples
+
+### Command Examples
+
+```markdown
+```sh
+coder server --disable-template-insights
+```
+```
+
+### Environment Variables
+
+```markdown
+```sh
+CODER_DISABLE_TEMPLATE_INSIGHTS=true
+```
+```
+
+### Code Comments
+
+- Keep minimal
+- Explain non-obvious parameters
+- Use `# Comment` for shell, `// Comment` for other languages
+
+## Links and References
+
+### Internal Links
+
+Use relative paths from current file location:
+
+- `[Template Permissions](./template-permissions.md)`
+- `[API documentation](../../reference/api/insights.md)`
+
+### Cross-References
+
+- Link to related documentation at the end
+- Use descriptive text: "Learn about [template access control](./template-permissions.md)"
+- Not just: "[Click here](./template-permissions.md)"
+
+### API References
+
+Link to specific endpoints:
+
+```markdown
+- `/api/v2/insights/templates` - Template usage metrics
+```
+
+## Accuracy Standards
+
+### Specific Numbers Matter
+
+Document exact values from code:
+
+- **Thresholds**: "green < 150ms, yellow 150-300ms, red ≥300ms"
+- **Time intervals**: "daily for templates < 5 weeks old, weekly for 5+ weeks"
+- **Counts and limits**: Use precise numbers, not approximations
+
+### Permission Actions
+
+- Use exact RBAC action names from code (e.g., `view_insights` not "view insights")
+- Reference permission system correctly (`template:view_insights` scope)
+- Specify which roles have permissions by default
+
+### API Endpoints
+
+- Use full, correct paths (e.g., `/api/v2/insights/templates` not `/insights/templates`)
+- Link to generated API documentation in `docs/reference/api/`
+
+## Documentation Manifest
+
+**All documentation pages must be added to `docs/manifest.json`** to appear in navigation:
+
+```json
+{
+  "title": "Template Insights",
+  "description": "Monitor template usage and application metrics",
+  "path": "./admin/templates/template-insights.md"
+}
+```
+
+- **title**: Display name in navigation
+- **description**: Brief summary (used in some UI contexts)
+- **path**: Relative path from `docs/` directory
+- **state** (optional): `["premium"]` or `["beta"]` for feature badges
+
+Place new pages in logical sections matching existing hierarchy in manifest.json.
+
+## Proactive Documentation
+
+When documenting features that depend on upcoming PRs:
+
+1. **Reference the PR explicitly** - Mention PR number and what it adds
+2. **Document the feature anyway** - Write as if feature exists
+3. **Link to auto-generated docs** - Point to CLI reference sections that will be created
+4. **Update PR description** - Note documentation is included proactively
+
+**Example**: Template Insights docs include `--disable-template-insights` flag from PR #20940 before it merged, with link to `../../reference/cli/server.md#--disable-template-insights` that will exist when the PR lands.
+
+## Special Sections
+
+### Troubleshooting
+
+- **H3 subheadings** for each issue
+- Format: Issue description followed by solution steps
+
+### Prerequisites
+
+- Bullet or numbered list
+- Include version requirements, dependencies, permissions
+
+## Formatting Conventions
+
+### Text Formatting
+
+- **Bold** (`**text**`): UI elements, important concepts, labels
+- *Italic* (`*text*`): Rare, mainly for emphasis
+- `Code` (`` `text` ``): Commands, file paths, parameter names
+
+### Tables
+
+- Use for comparing options, listing parameters, showing permissions
+- Left-align text, right-align numbers
+- Keep simple - avoid nested formatting when possible
+
+### Code Blocks
+
+- **Always specify language**: `` ```sh ``, `` ```yaml ``, `` ```go ``
+- Include comments for complex examples
+- Keep minimal - show only relevant configuration
+
+## Document Length
+
+- **Comprehensive but scannable**: Cover all aspects but use clear headings
+- **Break up long sections**: Use H3 subheadings for logical chunks
+- **Visual hierarchy**: Images and code blocks break up text
+
+## Auto-Generated Content
+
+Some content is auto-generated with comments:
+
+```markdown
+<!-- Code generated by 'make docs/...' DO NOT EDIT -->
+```
+
+Don't manually edit auto-generated sections.
+
+## Key Principles
+
+1. **Research first** - Verify against actual code implementation
+2. **Be precise** - Use exact numbers, permission names, API paths
+3. **Visual structure** - Organize around screenshots when available
+4. **Link everything** - Related docs, API endpoints, CLI references
+5. **Manifest inclusion** - Add to manifest.json for navigation

CLAUDE.md

@@ -197,6 +197,7 @@ clear what the new test covers.
 @.claude/docs/TESTING.md
 @.claude/docs/TROUBLESHOOTING.md
 @.claude/docs/DATABASE.md
+@.claude/docs/DOCS_STYLE_GUIDE.md
 
 ## Local Configuration
 

docs/admin/templates/index.md

@@ -60,6 +60,8 @@ needs of different teams.
   changes are reviewed and tested.
 - [Permissions and Policies](./template-permissions.md): Control who may access
   and modify your template.
+- [Template Insights](./template-insights.md): Monitor template usage, application
+  metrics, and user activity to optimize your templates.
 - [External Workspaces](./managing-templates/external-workspaces.md): Learn how to connect your existing infrastructure to Coder workspaces.
 
 <children></children>

docs/admin/templates/template-insights.md

@@ -0,0 +1,150 @@
+# Template Insights
+
+Template Insights provides detailed analytics and usage metrics for your Coder templates. This feature helps administrators and template owners understand how templates are being used, identify popular applications, and monitor user engagement.
+
+![Template Insights page](../../images/admin/templates/template-insights.png)
+
+## Accessing Template Insights
+
+To view Template Insights:
+
+1. Navigate to the **Templates** page in your Coder dashboard
+2. Select a template from the list
+3. Click the **Insights** tab
+
+> [!NOTE]
+> Template Insights requires the `view_insights` permission on the template. Template administrators and organization owners have this permission.
+
+## Overview
+
+The Template Insights page displays usage analytics across several key areas:
+
+<small>Template Insights showing weekly active users and connection latency metrics.</small>
+
+### Active Users
+
+The Weekly Active Users chart tracks the number of unique users who connected to workspaces from this template over time. This metric helps you:
+
+- Monitor template adoption trends
+- Identify usage patterns and peak periods
+- Plan infrastructure capacity based on user growth
+
+You can view data by daily intervals (default for templates less than 5 weeks old) or weekly intervals (default for templates 5 weeks or older). Use the date range picker to analyze specific time periods.
+
+### User Latency
+
+The connection latency table displays performance metrics for each user:
+
+- **P50 (Median)**: The median connection latency experienced by users
+- **P95**: The 95th percentile latency, indicating worst-case performance for most users
+
+Latency is color-coded for quick assessment:
+
+- **Green**: Good performance (< 150ms)
+- **Yellow**: Moderate performance (150-300ms)
+- **Red**: Poor performance (> 300ms)
+
+High latency may indicate network issues between users and workspaces, resource constraints on workspace hosts, or geographic distance between users and infrastructure.
+
+## Application Usage and User Activity
+
+Template Insights provides detailed metrics on how users interact with workspace applications and which users are most active.
+
+![App & IDE Usage and Activity by user](../../images/admin/templates/template-insights-apps-activity.png)
+
+<small>Application usage statistics and user activity rankings.</small>
+
+### App & IDE Usage
+
+The App & IDE Usage section shows which applications users are connecting through, ranked by total usage time.
+
+### Activity by User
+
+The Activity by user table lists users who have used workspaces from this template, sorted by total usage time. This information helps you:
+
+- Identify power users who may benefit from optimized resources
+- Spot users who might need additional support or training
+- Understand overall adoption of the template
+- Plan resource allocation based on actual usage patterns
+
+## Template Parameters
+
+Understanding which parameter values users select when creating workspaces helps you optimize template defaults and identify unused options.
+
+![Template Parameters distribution](../../images/admin/templates/template-insights-parameters.png)
+
+<small>Distribution of memory usage threshold and region parameter selections.</small>
+
+The Template Parameters section shows the distribution of values selected for each parameter in your template. In the example above:
+
+- **Memory usage threshold**: Shows that most workspaces (934) use the default 80% threshold, with only a few using higher thresholds
+- **Region**: Displays geographic distribution of workspaces, with Pittsburgh being the most popular region (232 workspaces), followed by Falkenstein (137) and Cape Town (93)
+
+This information helps you:
+
+- Understand common configuration choices
+- Identify unused parameter options that could be removed
+- Optimize default values based on actual usage patterns
+- Plan regional infrastructure capacity
+
+## Use Cases
+
+Template Insights helps you make data-driven decisions about your Coder deployment:
+
+- **Template Optimization**: Remove unused applications or features, adjust default parameters based on actual usage patterns, and optimize resource allocations for common use cases
+- **Capacity Planning**: Monitor active user trends to predict infrastructure capacity needs, plan for scaling during peak usage periods, and identify underutilized templates that could be consolidated
+- **User Support**: Identify users with high latency connections who may need network troubleshooting, low usage who might need onboarding help, or specific application preferences for targeted support
+- **ROI and Reporting**: Generate reports on developer productivity through usage metrics, template adoption rates, and infrastructure utilization efficiency
+
+## Permissions
+
+Template Insights respects Coder's RBAC (Role-Based Access Control) system:
+
+- **Template Administrators**: Can view insights for templates they manage
+- **Organization Owners**: Can view insights for all templates in their organization
+- **Regular Users**: Cannot access Template Insights by default
+
+To grant a user access to Template Insights for a specific template, assign them the `view_insights` permission through [template permissions](./template-permissions.md).
+
+Access to insights data is controlled entirely through permissions. To prevent users from viewing insights for a template, do not grant them the `view_insights` permission.
+
+### Disabling Template Insights
+
+To completely disable Template Insights collection and display across your deployment, use the `--disable-template-insights` server flag:
+
+```sh
+coder server --disable-template-insights
+```
+
+Or set the environment variable:
+
+```sh
+CODER_DISABLE_TEMPLATE_INSIGHTS=true
+```
+
+When disabled, insights data will not be collected or stored, and the Insights tab will not be available in the UI.
+
+See the [server CLI reference](../../reference/cli/server.md#--disable-template-insights) for more details.
+
+## Data Privacy
+
+Template Insights aggregates usage data while respecting user privacy:
+
+- Individual workspace sessions are aggregated
+- User activity shows total usage time, not detailed session logs
+- No personally identifiable information beyond usernames is exposed
+- Connection latency is measured from agent statistics, not network monitoring
+
+## API Access
+
+Template Insights data is also available via the Coder API. See the [API documentation](../../reference/api/insights.md) for details on:
+
+- `/api/v2/insights/templates` - Template usage metrics
+- `/api/v2/insights/user-activity` - User activity data
+- `/api/v2/insights/user-latency` - Connection latency metrics
+
+## Related Documentation
+
+- [Template Permissions](./template-permissions.md) - Learn about template access control
+- [Creating Templates](./creating-templates.md) - Build templates with usage tracking in mind
+- [Managing Templates](./managing-templates/change-management.md) - Use insights to inform template updates

docs/manifest.json

@@ -686,6 +686,11 @@
 							"path": "./admin/templates/template-permissions.md",
 							"state": ["premium"]
 						},
+						{
+							"title": "Template Insights",
+							"description": "Monitor template usage and application metrics",
+							"path": "./admin/templates/template-insights.md"
+						},
 						{
 							"title": "Troubleshooting Templates",
 							"description": "Learn how to troubleshoot template issues",