---
allowed-tools: Read, Write, Edit, Bash, Grep, Glob
argument-hint: --dry-run | --force
description: Regenerate library reference documentation (docs/library-reference.md) by scanning all monorepo libraries
---

# /docs:refresh-reference - Regenerate Library Reference

Regenerate the library reference documentation (`docs/library-reference.md`) by scanning all libraries in the monorepo.

## Tasks

### 1. Scan Monorepo Structure
```bash
# List all libraries
find libs/ -name "project.json" -type f | sort

# Count total libraries
find libs/ -name "project.json" -type f | wc -l
```

### 2. Extract Library Information

For each library, extract from `project.json`:
- **Project name**: `name` field
- **Path**: Directory path
- **Tags**: For categorization (type, domain)
- **Targets**: Available commands (build, test, lint)

### 3. Determine Path Aliases

Read `tsconfig.base.json` to get path mappings:
```bash
# Extract paths section
cat tsconfig.base.json | grep -A 200 '"paths"'
```

Map each library to its `@isa/*` alias.

### 4. Categorize Libraries by Domain

Group libraries into categories:
- **Availability** (1 library)
- **Catalogue** (1 library)
- **Checkout** (6 libraries)
- **Common** (3 libraries)
- **Core** (5 libraries)
- **CRM** (1 library)
- **Icons** (1 library)
- **OMS** (9 libraries)
- **Remission** (8 libraries)
- **Shared Components** (7 libraries)
- **UI Components** (17 libraries)
- **Utilities** (3 libraries)

### 5. Read Library READMEs

For each library, use `docs-researcher` agent to:
- Read library README.md (if exists)
- Extract description/purpose
- Extract key features
- Extract usage examples

### 6. Generate Library Entries

For each library, create entry with:
```markdown
#### `@isa/domain/layer/name`
**Path:** `libs/domain/layer/name`
**Type:** [Feature/Data Access/UI/Util]

Brief description from README or inferred from structure.

**Key Features:**
- Feature 1
- Feature 2

**Usage:**
```typescript
import { Component } from '@isa/domain/layer/name';
```
```

### 7. Create Domain Statistics

Calculate per domain:
- Total libraries count
- Breakdown by type (feature/data-access/ui/util)
- Key capabilities overview

### 8. Generate Table of Contents

Create hierarchical TOC:
```markdown
## Table of Contents
1. [Overview](#overview)
2. [Quick Stats](#quick-stats)
3. [Library Categories](#library-categories)
   - [Availability](#availability)
   - [Catalogue](#catalogue)
   - [Checkout](#checkout)
   ...
```

### 9. Add Metadata Header

Include document metadata:
```markdown
# Library Reference Guide

> **Last Updated:** [Current Date]
> **Total Libraries:** XX
> **Domains:** 12

## Quick Stats
- Availability: 1 | Catalogue: 1 | Checkout: 6 | Common: 3
- Core: 5 | CRM: 1 | Icons: 1 | OMS: 9 | Remission: 8
- Shared Components: 7 | UI Components: 17 | Utilities: 3
```

### 10. Add Usage Guidelines

Include quick reference section:
```markdown
## How to Use This Guide

### Finding a Library
1. Check the domain category (e.g., OMS, Checkout, UI Components)
2. Look for the specific feature or component you need
3. Note the import path alias (e.g., `@isa/oms/feature-return-search`)

### Import Syntax
All libraries use path aliases defined in `tsconfig.base.json`:

```typescript
// Feature libraries
import { Component } from '@isa/domain/feature/name';

// Data access services
import { Service } from '@isa/domain/data-access';

// UI components
import { ButtonComponent } from '@isa/ui/buttons';

// Utilities
import { helper } from '@isa/utils/validation';
```
```

### 11. Add Cross-References

Link related libraries:
```markdown
**Related Libraries:**
- [`@isa/oms/data-access`](#isaomsdataaccess) - OMS data services
- [`@isa/ui/buttons`](#isauibuttons) - Button components
```

### 12. Include Testing Information

For each library, note test framework:
```markdown
**Testing:** Vitest | Jest
**Test Command:** `npx nx test [library-name] --skip-nx-cache`
```

### 13. Validate Generated Documentation

Checks:
- All libraries included (compare count)
- All path aliases correct
- No broken internal links
- Consistent formatting
- Alphabetical ordering within categories

### 14. Update CLAUDE.md Reference

Update CLAUDE.md to reference new library-reference.md:
```markdown
#### Library Reference Guide

The monorepo contains **62 libraries** organized across 12 domains.
For quick lookup, see **[`docs/library-reference.md`](docs/library-reference.md)**.
```

### 15. Create Backup

Before overwriting:
```bash
# Backup existing file
cp docs/library-reference.md docs/library-reference.md.backup.$(date +%s)
```

### 16. Write New Documentation

Write to `docs/library-reference.md` with generated content.

## Output Format

**Generated File Structure:**
```markdown
# Library Reference Guide

> Last Updated: [Date]
> Total Libraries: XX
> Domains: 12

## Table of Contents
[Auto-generated TOC]

## Overview
[Introduction and usage guide]

## Quick Stats
[Statistics by domain]

## Library Categories

### Availability
#### @isa/availability/data-access
[Details...]

### Catalogue
[Details...]

[... all domains ...]

## Appendix

### Path Aliases
[Quick reference table]

### Testing Frameworks
[Framework by library]

### Nx Commands
[Common commands]
```

## Output Summary
```
Library Reference Documentation Generated
==========================================

📊 Statistics
-------------
Total libraries scanned: XX
Libraries documented: XX
Domains covered: 12

📝 Documentation Structure
--------------------------
- Table of Contents: ✅
- Quick Stats: ✅
- Library categories: XX
- Total entries: XX

🔍 Quality Checks
-----------------
- All libraries included: ✅/❌
- Path aliases validated: ✅/❌
- Internal links verified: ✅/❌
- Consistent formatting: ✅/❌

💾 Files Updated
----------------
- docs/library-reference.md: ✅
- Backup created: docs/library-reference.md.backup.[timestamp]

📈 Changes from Previous Version
---------------------------------
- Libraries added: XX
- Libraries removed: XX
- Descriptions updated: XX

🎯 Next Steps
-------------
1. Review generated documentation
2. Verify library descriptions are accurate
3. Add missing usage examples if needed
4. Commit changes: git add docs/library-reference.md
```

## Error Handling
- Missing project.json: Skip and report
- No README found: Use generic description
- Path alias mismatch: Flag for manual review
- Broken links: List for correction

## Automation Tips
Can be run:
- After adding new libraries
- During documentation updates
- As pre-release validation
- In CI/CD pipeline

## References
- CLAUDE.md Library Organization section
- tsconfig.base.json (path aliases)
- Individual library README.md files
- docs/library-reference.md (existing documentation)
