Smart Initref

Initialize reference documentation for a project by scanning the codebase and generating a structured knowledge base of APIs, components, services, and types.

When to Use This Command

Run this command when...

• You are setting up a new project and want to bootstrap developer reference documentation
• You want to auto-generate API documentation from source code annotations and types
• You need a structured overview of all components, services, and their relationships

Avoid this command when...

• Documentation already exists and only needs incremental updates
• You need user-facing guides or tutorials rather than developer API reference

Quick Start

Copy
# .claude/commands/smart-initref.md
---
allowed-tools: ["Read", "Glob", "Grep", "Write"]
---
Scan the codebase for components, services, APIs, and types.
Generate structured reference documentation from source code.

Example usage:

/smart-initref

Example output:

Scanning codebase...
  Components: 24 React components found
  Services:   8 service classes found
  API Routes: 15 endpoints found
  Types:      42 TypeScript interfaces found

Generated: docs/reference/
  components.md    (24 entries)
  services.md      (8 entries)
  api-routes.md    (15 entries)
  types.md         (42 entries)

Core Concepts

Concept	Description
Code scanning	Traverses source files to find all documentable entities
Type extraction	Pulls TypeScript interfaces, function signatures, and JSDoc comments
Relationship mapping	Identifies imports and dependency links between modules
Template generation	Creates structured markdown entries from extracted metadata

Codebase --> Scan Files --> Extract Entities
                                |
                   +-----+------+------+
                   |     |      |      |
               Components Services APIs  Types
                   |     |      |      |
                   +-----+------+------+
                          |
                  Generate Reference Docs

Configuration

Option	Default	Description
output	docs/reference	Directory where generated documentation is written
format	markdown	Output format (markdown, json, html)
include	src/	Directories to scan for source entities
exclude	tests,mocks	Directories to skip during scanning
overwrite	false	Whether to overwrite existing documentation files

Best Practices

1. Run once at project start -- use this to bootstrap documentation, then maintain it by hand.
2. Add JSDoc/TSDoc comments -- the scanner extracts inline documentation and uses it to enrich the reference.
3. Review generated docs -- automated documentation needs human review for accuracy and tone.
4. Keep reference separate from guides -- reference docs describe what exists; guides explain how to use it.
5. Re-run after major refactors -- significant structural changes warrant regenerating the reference baseline.

Common Issues

1. Missing entities -- files outside the configured include path are not scanned. Adjust the include directories.
2. Sparse documentation output -- if source code lacks comments, the reference will be minimal. Add JSDoc/TSDoc annotations first.
3. Overwrite conflict -- keep overwrite set to false (the default) to avoid accidentally replacing hand-edited documentation.