# Reports API

Knowledge management with witness-based validation, hierarchical organization, and views.

## Quick Start

```typescript
handler: async (input, ctx) => {
  // Write a report
  const result = await ctx.majk.reports.write_report({
    path: '/research/api-analysis.md',
    content: '# API Analysis\n\nFindings from the API review...',
    title: 'API Analysis Report',
    tags: ['research', 'api'],
    witness: { file: { path: 'src/api.ts', exists: true } }
  });

  // Read it back
  const report = await ctx.majk.reports.read_report({ report: result.id });
  return { reportId: result.id };
}
```

## API Reference

### write_report(input)

Write a report to the knowledge base.

```typescript
const result = await ctx.majk.reports.write_report({
  content: string,              // Markdown content
  path: string,                 // Path like '/research/topic.md'
  title?: string,
  partOf?: { parent: string, placeholder?: string },  // Hierarchical relationship
  refs?: string[],              // Related report IDs
  tags?: string[],
  status?: string,              // 'draft', 'review', 'final'
  witness?: Witness             // Validation criteria
});
// Returns: { id, path, uri, title?, hasWitness, created }
```

### read_report(input)

Read a report with optional content expansion.

```typescript
const report = await ctx.majk.reports.read_report({
  report: string,               // ID or path
  view?: string,                // View name
  expand?: 'link' | 'inline' | 'inline-linked',
  expandDepth?: number,
  offset?: number,              // Line offset
  limit?: number,               // Line limit
  validate?: boolean,           // Run witness validation
  workingDirectory?: string
});
// Returns: { id, path, content, validation, ... }
```

### list_reports(input?)

List and search reports.

```typescript
const { reports, total, hasMore } = await ctx.majk.reports.list_reports({
  view?: string,
  pathPrefix?: string,          // Filter by path prefix
  tags?: string[],
  status?: string,
  hasWitness?: boolean,
  search?: string,              // Text search
  limit?: number,
  offset?: number
});
```

### delete_report(input)

Delete a report.

```typescript
const { deleted } = await ctx.majk.reports.delete_report({ report: string });
```

### update_report(input)

Update with line-based edits.

```typescript
const result = await ctx.majk.reports.update_report({
  report: string,
  edits: [
    { line: 5, content: 'Updated line 5' },
    { lines: [10, 15], content: 'Replace lines 10-15' },
    { after: 20, content: 'Insert after line 20' },
    { line: 25, delete: true }
  ],
  validate?: boolean
});
```

### reorganize_reports(input)

Batch move reports.

```typescript
const result = await ctx.majk.reports.reorganize_reports({
  moves: [
    { from: '/old/path.md', to: '/new/path.md' }
  ]
});
```

## Template Workflow

### start_report(input)

Start a report from a template.

```typescript
const draft = await ctx.majk.reports.start_report({
  template: 'research-report',
  topic: 'API Security',
  sections: { summary: 'Initial findings...' },
  refs: { codebase: ['src/api.ts', 'src/auth.ts'] }
});
// Returns: { handle, preview, missing: { sections, refs } }
```

### update_draft(input)

Update a draft report.

```typescript
const updated = await ctx.majk.reports.update_draft({
  handle: string,
  sections: { analysis: 'Detailed analysis...' },
  refs: { tests: 'tests/api.test.ts' }
});
```

### preview_draft(input)

Preview before finalizing.

```typescript
const preview = await ctx.majk.reports.preview_draft({
  handle: string,
  validate: true
});
// Returns: { rendered, missing, validation?, ready }
```

### finalize_report(input)

Finalize and save the report.

```typescript
const result = await ctx.majk.reports.finalize_report({
  handle: string,
  force?: boolean  // Finalize even with validation warnings
});
```

## Views

### create_view(input)

Create an LLM-powered view.

```typescript
const view = await ctx.majk.reports.create_view({
  name: 'Security Review',
  philosophy: 'Organize reports by security domain and risk level',
  categorizeExisting: true
});
```

### list_views()

```typescript
const { views } = await ctx.majk.reports.list_views();
// views: Array<{ id, name, isDefault, reportCount }>
```

### get_view_structure(input)

Get view tree structure.

```typescript
const structure = await ctx.majk.reports.get_view_structure({ view: 'Security Review' });
// Returns: { viewId, viewName, tree, reportCount }
```

### delete_view(input)

```typescript
const { deleted } = await ctx.majk.reports.delete_view({ view: string });
```

## Import/Export

### import_document(input)

Import a file into the knowledge base.

```typescript
const result = await ctx.majk.reports.import_document({
  file: '/path/to/document.md',
  topic: 'research',
  title: 'Imported Doc',
  tags: ['imported'],
  cleanup: true  // Delete source after import
});
```

### export_report(input)

Export a report to file.

```typescript
const result = await ctx.majk.reports.export_report({
  report: string,
  outputPath: '/output/report.pdf',
  format: 'markdown' | 'html' | 'pdf' | 'docx',
  mode: 'single' | 'hierarchy' | 'inlined'
});
```

### export_all_reports(input)

Export all reports.

```typescript
const result = await ctx.majk.reports.export_all_reports({
  outputDir: '/output/',
  format: 'markdown'
});
```

## Hierarchical Reports

```typescript
// Create master report
const master = await ctx.majk.reports.write_report({
  path: '/research/security/security.md',
  content: '# Security Analysis\n\n{{@section:auth}}\n{{@section:api}}'
});

// Create child sections
await ctx.majk.reports.write_report({
  path: '/research/security/sections/01-auth.md',
  content: '## Authentication\n...',
  partOf: { parent: master.id, placeholder: 'auth' }
});
```

## Best Practices

1. **Use meaningful paths** - Organize reports hierarchically
2. **Add witnesses** - Validate reports stay accurate
3. **Use views** - Organize reports by perspective
4. **Tag consistently** - Enable filtering and discovery
5. **Use templates** - Ensure consistent report structure

## Next Steps

Run `npx @majkapp/plugin-kit --knowledge` - Knowledge tree API
Run `npx @majkapp/plugin-kit --delegation` - Task delegation