---
allowed-tools: Read, Write, Edit, Bash, Grep, Glob, Task
argument-hint: [library-name]
description: Generate or update README.md for a specific library with comprehensive documentation
---

# /docs:library - Generate/Update Library README

Generate or update README.md for a specific library with comprehensive documentation.

## Parameters
- `library-name`: Name of library (e.g., `oms-feature-return-search`)

## Tasks

### 1. Locate Library

```bash
# Find library directory
find libs/ -name "project.json" -path "*[library-name]*"

# Verify library exists
if [ ! -d "libs/[path-to-library]" ]; then
  echo "Library not found"
  exit 1
fi
```

### 2. Extract Library Information

Read `project.json`:
- Library name
- Source root
- Available targets (build, test, lint)
- Tags (domain, type)

Read `tsconfig.base.json`:
- Path alias (`@isa/domain/layer/name`)
- Entry point (`src/index.ts`)

### 3. Analyze Library Structure

Scan library contents:
```bash
# List main source files
ls -la libs/[path]/src/lib/

# Identify components
find libs/[path]/src -name "*.component.ts"

# Identify services
find libs/[path]/src -name "*.service.ts"

# Identify models/types
find libs/[path]/src -name "*.model.ts" -o -name "*.interface.ts"

# Check for exports
cat libs/[path]/src/index.ts
```

### 4. Use docs-researcher for Similar READMEs

Use `docs-researcher` agent to find similar library READMEs in the same domain for reference structure and style.

### 5. Determine Library Type and Template

**Feature Library Template:**
```markdown
# [Library Name]

> **Type:** Feature Library
> **Domain:** [OMS/Remission/Checkout/etc]
> **Path:** `libs/[domain]/feature/[name]`

## Overview

[Brief description of what this feature does]

## Features

- Feature 1: [Description]
- Feature 2: [Description]
- Feature 3: [Description]

## Installation

This library is part of the ISA-Frontend monorepo. Import it using:

```typescript
import { ComponentName } from '@isa/[domain]/feature/[name]';
```

## Usage

### Basic Example

```typescript
import { Component } from '@angular/core';
import { FeatureComponent } from '@isa/[domain]/feature/[name]';

@Component({
  selector: 'app-example',
  standalone: true,
  imports: [FeatureComponent],
  template: `
    <feature-component [input]="value" (output)="handleEvent($event)">
    </feature-component>
  `
})
export class ExampleComponent {
  value = 'example';

  handleEvent(event: any) {
    console.log(event);
  }
}
```

### Advanced Usage

[More complex examples if applicable]

## API Reference

### Components

#### FeatureComponent

**Selector:** `feature-component`

**Inputs:**
- `input` (string): Description of input

**Outputs:**
- `output` (EventEmitter<any>): Description of output

**Example:**
```html
<feature-component [input]="value" (output)="handleEvent($event)">
</feature-component>
```

### Services

[If applicable]

### Models

[If applicable]

## Testing

This library uses [Vitest/Jest] for testing.

Run tests:
```bash
npx nx test [library-name] --skip-nx-cache
```

Run with coverage:
```bash
npx nx test [library-name] --skip-nx-cache --coverage
```

## Dependencies

**External Dependencies:**
- [List of external packages if any]

**Internal Dependencies:**
- [`@isa/[dependency]`](../[path]) - Description

## Development

### Project Structure

```
libs/[domain]/feature/[name]/
├── src/
│   ├── lib/
│   │   ├── components/
│   │   ├── services/
│   │   └── models/
│   ├── index.ts
│   └── test-setup.ts
├── project.json
└── README.md
```

### Build

```bash
npx nx build [library-name]
```

### Lint

```bash
npx nx lint [library-name]
```

## Related Documentation

- [CLAUDE.md](../../../../CLAUDE.md) - Project guidelines
- [Testing Guidelines](../../../../docs/guidelines/testing.md)
- [Library Reference](../../../../docs/library-reference.md)

## Related Libraries

- [`@isa/[related-lib-1]`](../[path]) - Description
- [`@isa/[related-lib-2]`](../[path]) - Description
```

**Data Access Library Template:**
```markdown
# [Library Name]

> **Type:** Data Access Library
> **Domain:** [Domain]
> **Path:** `libs/[domain]/data-access`

## Overview

Data access layer for [Domain] domain. Provides services and state management for [domain-specific functionality].

## Features

- API client integration with [API names]
- NgRx Signals store for state management
- Type-safe data models with Zod validation
- Error handling and retry logic

## Installation

```typescript
import { ServiceName } from '@isa/[domain]/data-access';
```

## Services

### ServiceName

[Service description]

**Methods:**

#### `getById(id: string): Observable<Model>`
[Method description]

**Parameters:**
- `id` (string): Description

**Returns:** `Observable<Model>`

**Example:**
```typescript
this.service.getById('123').subscribe({
  next: (data) => console.log(data),
  error: (err) => console.error(err)
});
```

## State Management

This library uses NgRx Signals for state management.

### Store

```typescript
import { injectStore } from '@isa/[domain]/data-access';

export class Component {
  store = injectStore();

  // Access state
  items = this.store.items;
  loading = this.store.loading;

  // Call methods
  ngOnInit() {
    this.store.loadItems();
  }
}
```

## Models

### Model Name

```typescript
interface ModelName {
  id: string;
  property: type;
}
```

Validated with Zod schema for runtime type safety.

## Testing

[Testing section similar to feature library]

## API Integration

This library integrates with the following Swagger-generated API clients:

- `@generated/swagger/[api-name]`

[Additional API documentation]
```

**UI Component Library Template:**
```markdown
# [Library Name]

> **Type:** UI Component Library
> **Path:** `libs/ui/[name]`

## Overview

Reusable UI components for [purpose]. Part of the ISA design system.

## Components

### ComponentName

[Component description]

**Selector:** `ui-component-name`

**Styling:** Uses Tailwind CSS with ISA design tokens

**Example:**
```html
<ui-component-name variant="primary" size="md">
  Content
</ui-component-name>
```

## Variants

- **primary**: Default primary styling
- **secondary**: Secondary styling
- **accent**: Accent color

## Sizes

- **sm**: Small (24px height)
- **md**: Medium (32px height)
- **lg**: Large (40px height)

## Accessibility

- ARIA labels included
- Keyboard navigation supported
- Screen reader friendly

## Storybook

View component documentation and examples:

```bash
npm run storybook
```

Navigate to: UI Components → [Component Name]

## Testing

Includes E2E test attributes:
- `data-what="component-name"`
- `data-which="variant"`

[Rest of testing section]
```

### 6. Extract Code Examples

Scan library code for:
- Public component selectors
- Public API methods
- Input/Output properties
- Common usage patterns

Use `Read` tool to extract from source files.

### 7. Document Exports

Parse `src/index.ts` to document public API:
```typescript
// Read barrel export
export * from './lib/component';
export * from './lib/service';
export { PublicInterface } from './lib/models';
```

Document each export with:
- Type (Component/Service/Interface/Function)
- Purpose
- Basic usage

### 8. Add Testing Information

Based on test framework (from project.json):
- Test command
- Framework (Vitest/Jest)
- Coverage command
- Link to testing guidelines

### 9. Create Dependency Graph

List internal and external dependencies:
```bash
# Use Nx to show dependencies
npx nx graph --focus=[library-name]

# Extract from package.json and imports
```

### 10. Add E2E Attributes Documentation

For UI/Feature libraries, document E2E attributes:
```markdown
## E2E Testing

This library includes E2E test attributes for automated testing:

| Element | data-what | data-which | Purpose |
|---------|-----------|------------|---------|
| Submit button | submit-button | form-primary | Main form submission |
| Cancel button | cancel-button | form-primary | Cancel action |

Use these attributes in your E2E tests:
```typescript
const submitBtn = page.locator('[data-what="submit-button"][data-which="form-primary"]');
```
```

### 11. Generate/Update README

Write or update `libs/[path]/README.md` with generated content.

### 12. Validate README

Checks:
- All links work (relative paths correct)
- Code examples are valid TypeScript
- Import paths use correct aliases
- No TODO or placeholder text
- Consistent formatting
- Proper markdown syntax

### 13. Add to Git (if new)

```bash
git add libs/[path]/README.md
```

## Output Format
```
Library README Generated
========================

Library: [library-name]
Type: [Feature/Data Access/UI/Util]
Path: libs/[domain]/[layer]/[name]

📝 README Sections
------------------
✅ Overview
✅ Features
✅ Installation
✅ Usage Examples
✅ API Reference
✅ Testing
✅ Dependencies
✅ Development Guide

📊 Documentation Stats
----------------------
Total sections: XX
Code examples: XX
API methods documented: XX
Components documented: XX

🔗 Links Validated
-------------------
Internal links: XX/XX valid
Relative paths: ✅ Correct

💡 Highlights
-------------
- Documented XX public exports
- XX code examples included
- E2E attributes documented
- Related libraries linked

📁 File Updated
---------------
Path: libs/[domain]/[layer]/[name]/README.md
Size: XX KB
Lines: XX

🎯 Next Steps
-------------
1. Review generated README
2. Add any domain-specific details
3. Add usage examples if needed
4. Commit: git add libs/[path]/README.md
```

## Auto-Enhancement

If existing README found:
- Preserve custom sections
- Update outdated examples
- Add missing sections
- Fix broken links
- Update import paths

Prompt:
```
Existing README found. What would you like to do?
1. Generate new (overwrite)
2. Enhance existing (preserve custom content)
3. Cancel
```

## Quality Checks

- Import examples use correct path aliases
- Code examples are syntactically correct
- Links to related docs work
- API documentation complete
- Testing section accurate

## References
- CLAUDE.md Library Organization section
- Use `docs-researcher` to find reference READMEs
- Storybook for UI component examples
- project.json for library configuration
