Phase 5: Documentation

## Phase 5: Documentation

**Part of Epic**: #208
**Timeline**: 1-2 days
**Priority**: Medium (important but not blocking)
**Depends On**: #209, #210, #211, #212

## Overview

Update all documentation to reflect the new deployment architecture, create persona-based installation guides, document the release process, and write comprehensive BDD feature files.

## Tasks

### 5.1 Update AGENTS.md
- [ ] Add "Build System Configuration" section
- Document all Nuke parameters
- Explain environment variable overrides
- Show CI vs local configuration
- [ ] Add "Changelog-Driven Versioning" section
- Explain version format (SemVer)
- Document pre-release types (alpha, beta, preview, rc)
- Show release preparation workflow
- Explain PrepareRelease target usage
- [ ] Add "Dual Distribution Strategy" section
- NuGet tool package for .NET developers
- Platform executables for non-SDK users
- When to recommend each approach
- [ ] Update existing sections if needed

### 5.2 Update CLAUDE.md
- [ ] Add build organization guidance
- [ ] Document PrepareRelease workflow
- [ ] Add testing requirements summary
- [ ] Update commit message examples
- [ ] Add release preparation checklist

### 5.3 Update README.md
- [ ] Add persona-based installation instructions:
- **For .NET Developers**: dotnet tool install
- **For Shell Scripts/Containers**: Install script or GitHub releases
- **For CI/CD**: Choose based on environment
- [ ] Add version badge (from NuGet or GitHub)
- [ ] Update quick start examples
- [ ] Ensure examples use "morphir" command

### 5.4 Create DEPLOYMENT.md
- [ ] Document release process for maintainers:
1. Update [Unreleased] during development
2. Run PrepareRelease when ready
3. Create release branch and PR
4. After merge, create and push tag
5. Monitor deployment workflow
- [ ] Add troubleshooting section
- [ ] Document rollback procedures
- [ ] Add deployment checklist
- [ ] Link to PRD for architecture details

### 5.5 Write BDD Feature Files
- [ ] Create `tests/Morphir.E2E.Tests/Features/ToolInstallation.feature`
- Install from NuGet
- Update tool
- Uninstall tool
- Verify command availability
- [ ] Create `tests/Morphir.E2E.Tests/Features/ExecutableDownload.feature`
- Download from GitHub releases
- Execute standalone
- Verify version output
- [ ] Update existing feature files if needed

### 5.6 Update Contributing Documentation
- [ ] Update docs/content/contributing/ if needed
- [ ] Document new build targets
- [ ] Explain testing requirements
- [ ] Show how to run build tests locally

## Documentation Structure

### README.md Changes

```markdown
## Installation

### For .NET Developers

If you have the .NET SDK installed:

```bash
dotnet tool install -g Morphir.Tool
morphir --version
```

### For Shell Scripts / Containers

If you don't have .NET SDK or need a standalone executable:

**Linux/macOS:**
```bash
curl -sSL https://get.morphir.org | bash
```

**Windows:**
```powershell
irm https://get.morphir.org/install.ps1 | iex
```

**Manual Download:**
Download from [GitHub Releases](https://github.com/finos/morphir-dotnet/releases)

### For CI/CD Pipelines

Choose based on your environment...
```

### DEPLOYMENT.md Structure

```markdown
# Morphir .NET Deployment Guide

## Release Process

### Prerequisites
- Write access to repository
- NUGET_TOKEN secret configured
- CHANGELOG.md up to date

### Steps

1. **Prepare Release**
```bash
./build.sh PrepareRelease --release-version X.Y.Z
```

2. **Review Changes**
```bash
git diff --staged
```

3. **Create Release Branch**
...

## Troubleshooting
## Rollback Procedures
## Deployment Checklist
```

## Verification Checklist

- [ ] AGENTS.md updated with new sections
- [ ] CLAUDE.md reflects new workflows
- [ ] README.md has persona-based install instructions
- [ ] DEPLOYMENT.md created with complete guide
- [ ] BDD feature files written
- [ ] All code examples tested
- [ ] Links verified (no broken links)
- [ ] Spelling and grammar checked

## Testing Requirements

**Manual Verification**:
- [ ] Follow README install instructions (both methods)
- [ ] Follow DEPLOYMENT.md release process (dry run)
- [ ] Verify all links work
- [ ] Check code examples execute correctly
- [ ] Review with fresh eyes (or ask for review)

## Definition of Done

- All tasks completed
- All verification items checked
- Documentation is clear and accurate
- Examples are tested
- Ready for users and maintainers
- PR ready for review

## Dependencies

**Depends On**:
- #209 (needs project structure documentation)
- #210 (needs versioning workflow documentation)
- #211 (needs testing documentation)
- #212 (needs deployment workflow documentation)

## BDD Feature Files

### Example: ToolInstallation.feature

```gherkin
Feature: Morphir Tool Installation
As a .NET developer
I want to install Morphir as a dotnet tool
So that I can use it in my development workflow

Scenario: Install from NuGet
Given I am a .NET developer with SDK installed
When I run "dotnet tool install -g Morphir.Tool"
Then the tool should install successfully
And I should be able to run "morphir --version"
And the version should match CHANGELOG.md

Scenario: Update tool
Given Morphir.Tool is already installed
When I run "dotnet tool update -g Morphir.Tool"
Then the tool should update successfully
And the new version should be active

Scenario: Uninstall tool
Given Morphir.Tool is installed
When I run "dotnet tool uninstall -g Morphir.Tool"
Then the tool should uninstall successfully
And morphir command should not be available
```

## Notes

- Keep documentation concise and scannable
- Use real, tested examples
- Link to relevant sections for details
- Consider both experienced and new users
- Maintain consistency in terminology
- Use active voice and clear instructions

## Style Guide

- **Headings**: Use sentence case
- **Code blocks**: Always specify language
- **Commands**: Show full commands, not abbreviated
- **Links**: Use descriptive text, not "click here"
- **Examples**: Show both success and error cases where relevant

## Related Documentation

- **Epic**: #208
- **PRD**: [Phase 5](https://github.com/finos/morphir-dotnet/blob/feature/deployment-architecture-refactor/docs/content/contributing/design/prds/deployment-architecture-refactor.md#phase-5-documentation-1-2-days)
- **Keep a Changelog**: https://keepachangelog.com/
- **Writing Guide**: https://www.writethedocs.org/guide/

Read the Phase 5 PRD and dependent issues #209–#212 first, then inspect AGENTS.md, CLAUDE.md, README.md, docs/content/contributing/, and the existing tests/Morphir.E2E.Tests/Features/ files. The work is done when the requested guides, release documentation, installation examples, and BDD feature files are complete, linked, and manually verified against the checklist.

Written by the indexing model from the issue text.