trinity-method-sdk 2.0.8 → 2.1.0

package/dist/templates/shared/claude-commands/trinity-docs.md.template

@@ -1,2208 +0,0 @@
-# Trinity docs/ Directory Management
-
-**Purpose:** Launch APO (Documentation Specialist) to create, organize, and maintain the project's `docs/` directory with proper structure, seeded content, and navigation.
-
-**Use Case:** Create organized docs/ directory structure, seed initial documentation content, migrate scattered docs, generate navigation, validate links.
-
-**Deliverable:** docs/ organization report in `trinity/reports/DOCS-ORGANIZATION-{date}.md`
-
----
-
-## Overview
-
-The `/trinity-docs` command invokes APO (Documentation Specialist) to **create and organize** the `docs/` directory. This command creates a well-structured documentation directory with relevant starter content based on your project's actual codebase.
-
-**APO's Responsibilities:**
-- Analyze codebase to gather project context
-- Scan existing docs/ files and scattered documentation
-- Create hierarchical directory structure (guides/, api/, architecture/, reference/, images/)
-- Seed initial documentation content based on project type
-- Migrate scattered documentation files into organized structure
-- Auto-generate architecture documentation from codebase
-- Generate docs/README.md navigation file
-- Validate and fix documentation links
-- Integrate auto-generated API docs (TypeDoc, Rustdoc, etc.)
-- Provide actionable recommendations for empty categories
-
-**What This Command Does NOT Handle:**
-- ❌ Root README.md (use `/trinity-readme`)
-- ❌ CHANGELOG.md updates (use `/trinity-changelog`)
-- ❌ Trinity infrastructure files (trinity/, CLAUDE.md)
-- ❌ Technical source READMEs (src/README.md, tests/README.md)
-
----
-
-## CRITICAL: APO Must Perform Work DIRECTLY
-
-**APO is NOT a planning agent. APO is an EXECUTION agent for documentation.**
-
-**✅ APO MUST:**
-- ANALYZE codebase for project context **in this command execution**
-- CREATE docs/ directory structure **in this command execution**
-- SEED initial documentation content **in this command execution**
-- MIGRATE scattered documentation **in this command execution**
-- GENERATE architecture docs **in this command execution**
-- ORGANIZE existing documentation files **in this command execution**
-- VALIDATE and FIX documentation links **in this command execution**
-- Report COMPLETED work in Phase 5 (past tense: "Created docs/guides/getting-started.md")
-
-**❌ APO MUST NOT:**
-- Create work orders for docs organization
-- Create "recommendations" instead of performing organization
-- Skip work because "it's too much effort"
-- Defer work to future execution
-- Move Trinity infrastructure files (trinity/, CLAUDE.md)
-- Move technical source READMEs (src/README.md, etc.)
-
----
-
-## DOCUMENTATION RULES
-
-**These rules apply to ALL documentation created by this command. NO EXCEPTIONS.**
-
-### Rule 1: No Self-Serving Trinity Documentation
-
-**❌ FORBIDDEN:**
-- Including information about Trinity Method in project documentation
-- Explaining what Trinity Method is in README/docs
-- Mentioning Trinity agents (APO, MON, ROR, KIL, BAS, etc.) in user-facing docs
-- Documenting Trinity slash commands in project docs
-- Adding Trinity Method badges, links, or references to project documentation
-- Describing the Trinity Method SDK in project documentation
-
-**✅ CORRECT:**
-- Document the USER'S codebase exclusively
-- Focus on the project's functionality, architecture, and usage
-- Trinity Method is a development tool, not the subject of documentation
-- The project documentation is about the project, not about how it was documented
-
-**Why:** Trinity Method SDK is a tool for developers. The project's documentation should focus exclusively on the project's code, features, and usage - not on the development methodology used to create it.
-
----
-
-## When to Use `/trinity-docs`
-
-### Perfect Use Cases:
-✅ **New Project** - Setting up docs/ for the first time with seeded content
-✅ **Empty docs/** - docs/ exists but contains no useful documentation
-✅ **Disorganized docs/** - Files scattered without structure
-✅ **Missing Navigation** - No docs/README.md to guide users
-✅ **Documentation Growth** - docs/ has grown and needs reorganization
-✅ **Scattered Documentation** - .md files scattered across project
-✅ **Pre-Release** - Ensure documentation is well-organized with starter content
-
-### When NOT to Use:
-❌ **Root README Updates** - Use `/trinity-readme` instead
-❌ **CHANGELOG Updates** - Use `/trinity-changelog` instead
-❌ **API Documentation Generation** - Use TypeDoc, Rustdoc, etc. first (this command integrates them)
-
----
-
-## Usage
-
-### Basic Usage
-```bash
-/trinity-docs
-```
-
-APO performs complete docs/ creation and organization:
-1. Analyzes codebase for project context (framework, tech stack, architecture)
-2. Scans existing docs/ files and scattered documentation
-3. Creates directory structure (guides/, api/, architecture/, reference/, images/)
-4. Seeds initial documentation content based on project type
-5. Migrates scattered .md files into organized structure
-6. Auto-generates architecture documentation
-7. Integrates auto-generated API docs (TypeDoc, etc.)
-8. Validates and fixes documentation links
-9. Generates docs/README.md navigation with coverage metrics
-10. Generates comprehensive organization report
-
----
-
-## APO Execution Principles
-
-### Unlimited Token Budget
-
-**CRITICAL: APO has NO token budget limits for this command.**
-
-**✅ APO MUST:**
-1. Complete ALL 5 phases regardless of token usage
-2. Create ALL seeded content and organize ALL files (no "budget exceeded" stops)
-3. NEVER claim "token budget constraints" as reason for incomplete work
-
-**❌ APO MUST NOT:**
-1. Stop execution due to token concerns
-2. Skip phases due to "budget constraints"
-3. Defer work to future sessions
-
----
-
-## Phase Execution Rules
-
-**ALL 5 phases are MANDATORY. APO MUST execute phases in sequence.**
-
-**FORBIDDEN:**
-- ❌ Skipping phases
-- ❌ "Deferring" phases to future sessions
-- ❌ Claiming phases are "optional"
-
----
-
-## APO's 5-Phase docs/ Organization Process
-
-### Phase 1: Discovery & Codebase Analysis
-
-**Goal:** Scan existing documentation, detect scattered files, and analyze codebase for context
-
-**Step 1: Check if docs/ Exists**
-
-```bash
-# Check if docs/ directory exists
-if exists("docs/"):
-  docs_exists = true
-  # Scan docs/ directory
-  Use Glob pattern: "docs/**/*"
-else:
-  docs_exists = false
-  # Will create structure in Phase 2
-```
-
-**Step 2: Inventory Existing docs/ Files**
-
-If docs/ exists:
-
-```javascript
-docs_files = []
-docs_dirs = []
-
-for each path in glob_results:
-  if is_file(path):
-    docs_files.push(path)
-  else if is_directory(path):
-    docs_dirs.push(path)
-
-// Categorize files by type
-markdown_files = docs_files.filter(f => f.endsWith('.md'))
-image_files = docs_files.filter(f => f.endsWith('.png', '.jpg', '.svg', '.gif'))
-html_files = docs_files.filter(f => f.endsWith('.html'))  // TypeDoc, etc.
-other_files = docs_files.filter(f => not markdown nor image nor html)
-```
-
-**Step 3: Analyze Current docs/ Structure**
-
-```javascript
-has_guides_dir = docs_dirs.includes("docs/guides")
-has_api_dir = docs_dirs.includes("docs/api")
-has_architecture_dir = docs_dirs.includes("docs/architecture")
-has_reference_dir = docs_dirs.includes("docs/reference")
-has_images_dir = docs_dirs.includes("docs/images")
-has_navigation = docs_files.includes("docs/README.md")
-
-structure_score = (
-  (has_guides_dir ? 20 : 0) +
-  (has_api_dir ? 20 : 0) +
-  (has_architecture_dir ? 20 : 0) +
-  (has_reference_dir ? 20 : 0) +
-  (has_navigation ? 20 : 0)
-)
-```
-
-**Step 4: Scan for Scattered Documentation (ENHANCEMENT 3)**
-
-**CRITICAL: Identify documentation scattered outside docs/ for migration**
-
-```bash
-# Search entire project for .md files outside docs/
-Use Glob: "**/*.md"
-
-# EXCLUDE these patterns (DO NOT migrate):
-excluded_patterns = [
-  "node_modules/**",
-  ".git/**",
-  "docs/**",  # Already in docs/
-  "trinity/**",  # Trinity infrastructure - NEVER move
-  "**/CLAUDE.md",  # All CLAUDE.md files - NEVER move
-  "README.md",  # Root README - keep in root
-  "CHANGELOG.md",  # Root CHANGELOG - keep in root
-  "CONTRIBUTING.md",  # Root CONTRIBUTING - keep in root
-  "LICENSE",  # Root LICENSE - keep in root
-  "CODE_OF_CONDUCT.md",  # Root standards - keep in root
-  "SECURITY.md"  # Root standards - keep in root
-]
-
-scattered_docs = []
-
-for each file in glob_results:
-  # Skip if matches excluded patterns
-  if matches_any(file, excluded_patterns):
-    continue
-
-  # Categorize by filename/content patterns
-  category = detect_category(file)
-
-  # Check if it's a technical source README (src/README.md, tests/README.md)
-  if file.endsWith("/README.md"):
-    parent_dir = get_parent_directory(file)
-    if is_source_directory(parent_dir):  // src/, tests/, lib/, pkg/, etc.
-      continue  # Keep technical READMEs with source code
-
-  # This is orphaned documentation - mark for migration
-  scattered_docs.push({
-    file: file,
-    suggested_category: category
-  })
-
-// Category detection logic
-function detect_category(filename):
-  if matches("architecture*", "design*", "*-architecture", "*-design"):
-    return "docs/architecture/"
-
-  if matches("api*", "endpoints*", "*-api", "*-endpoints"):
-    return "docs/api/"
-
-  if matches("guide*", "tutorial*", "how-to*", "*-guide", "*-tutorial"):
-    return "docs/guides/"
-
-  if matches("*-reference", "spec*", "*-spec", "glossary*"):
-    return "docs/reference/"
-
-  // Default category
-  return "docs/guides/"
-```
-
-**Step 5: Codebase Context Analysis (ENHANCEMENT 1)**
-
-**CRITICAL: Gather project information to seed relevant documentation**
-
-```bash
-# Detect project type and extract metadata
-project_metadata = {}
-
-# Check package manifests
-if exists("package.json"):
-  package_json = read("package.json")
-  project_metadata.type = "Node.js"
-  project_metadata.name = package_json.name
-  project_metadata.version = package_json.version
-  project_metadata.description = package_json.description
-  project_metadata.dependencies = Object.keys(package_json.dependencies || {})
-  project_metadata.framework = detect_framework(package_json.dependencies)
-
-else if exists("Cargo.toml"):
-  cargo_toml = read("Cargo.toml")
-  project_metadata.type = "Rust"
-  project_metadata.name = cargo_toml.package.name
-  project_metadata.version = cargo_toml.package.version
-  project_metadata.description = cargo_toml.package.description
-
-else if exists("pyproject.toml") or exists("setup.py"):
-  project_metadata.type = "Python"
-  pyproject = read("pyproject.toml" or "setup.py")
-  # Extract Python project metadata
-
-else if exists("pubspec.yaml"):
-  pubspec = read("pubspec.yaml")
-  project_metadata.type = "Flutter"
-  project_metadata.name = pubspec.name
-  project_metadata.version = pubspec.version
-
-else if exists("go.mod"):
-  go_mod = read("go.mod")
-  project_metadata.type = "Go"
-  # Extract Go module info
-
-# Detect framework
-function detect_framework(dependencies):
-  if has("react"): return "React"
-  if has("next"): return "Next.js"
-  if has("express"): return "Express"
-  if has("vue"): return "Vue"
-  if has("@nestjs"): return "NestJS"
-  if has("django"): return "Django"
-  if has("flask"): return "Flask"
-  if has("fastapi"): return "FastAPI"
-  return "Unknown"
-
-# Scan source directory structure
-if exists("src/"):
-  src_structure = analyze_directory_structure("src/")
-  project_metadata.architecture = detect_architecture_pattern(src_structure)
-  project_metadata.entry_point = find_entry_point()
-
-# Detect architecture pattern
-function detect_architecture_pattern(structure):
-  if has_dirs(["controllers", "models", "views"]): return "MVC"
-  if has_dirs(["components", "pages", "hooks"]): return "React Component Architecture"
-  if has_dirs(["services", "repositories"]): return "Service Layer Architecture"
-  if has_dirs(["handlers", "middleware"]): return "Middleware-based Architecture"
-  return "Modular Architecture"
-
-# Check for existing documentation candidates
-if exists("CONTRIBUTING.md"):
-  project_metadata.has_contributing = true
-
-if exists(".env.example"):
-  project_metadata.has_env_example = true
-```
-
-**Step 6: Detect Auto-Generated API Documentation (ENHANCEMENT 8)**
-
-```bash
-# Detect TypeDoc (Node.js/TypeScript)
-if exists("docs/index.html") and exists("docs/modules.html"):
-  project_metadata.api_docs = {
-    type: "TypeDoc",
-    location: "docs/",
-    entry: "index.html"
-  }
-
-# Detect JSDoc
-if exists("docs/jsdoc/index.html"):
-  project_metadata.api_docs = {
-    type: "JSDoc",
-    location: "docs/jsdoc/",
-    entry: "index.html"
-  }
-
-# Detect Rustdoc
-if exists("target/doc/index.html"):
-  project_metadata.api_docs = {
-    type: "Rustdoc",
-    location: "target/doc/",
-    entry: "index.html"
-  }
-
-# Detect Sphinx (Python)
-if exists("docs/_build/html/index.html"):
-  project_metadata.api_docs = {
-    type: "Sphinx",
-    location: "docs/_build/html/",
-    entry: "index.html"
-  }
-```
-
-**Step 7: Detect Duplicate Documentation (ENHANCEMENT 6)**
-
-```bash
-# Find potential duplicates
-all_md_files = glob("**/*.md", exclude=excluded_patterns)
-duplicates = []
-
-for each file1 in all_md_files:
-  title1 = extract_title(file1)
-
-  for each file2 in all_md_files (after file1):
-    title2 = extract_title(file2)
-
-    # Check for similar titles
-    if similarity(title1, title2) > 0.8:
-      duplicates.push({file1, file2, similarity_score})
-
-    # Check for similar content
-    content_similarity = compare_content(file1, file2)
-    if content_similarity > 0.7:
-      duplicates.push({file1, file2, type: "content", similarity_score})
-```
-
-**APO Output:**
-
-```markdown
-=== PHASE 1: DISCOVERY & CODEBASE ANALYSIS ===
-
-**docs/ Exists:** {✅ YES | ❌ NO}
-
-**Current docs/ Files:** {count}
-- Markdown files: {count}
-- Image files: {count}
-- HTML files (TypeDoc/etc): {count}
-- Other files: {count}
-
-**Current docs/ Directories:** {count}
-- guides/: {✅ EXISTS | ❌ MISSING}
-- api/: {✅ EXISTS | ❌ MISSING}
-- architecture/: {✅ EXISTS | ❌ MISSING}
-- reference/: {✅ EXISTS | ❌ MISSING}
-- images/: {✅ EXISTS | ❌ MISSING}
-- Navigation (README.md): {✅ EXISTS | ❌ MISSING}
-
-**Structure Score:** {structure_score}/100
-- 0-25: Needs complete organization
-- 26-50: Needs significant organization
-- 51-75: Needs minor organization
-- 76-100: Well-organized
-
-**Scattered Documentation Found:** {scattered_docs.length} files
-{For each scattered doc:}
-- {file} → {suggested_category}
-
-**Duplicate Documentation:** {duplicates.length} potential duplicates
-{For each duplicate:}
-- {file1} ↔ {file2} (similarity: {score}%)
-
-**Project Context:**
-- **Type:** {project_metadata.type}
-- **Name:** {project_metadata.name}
-- **Version:** {project_metadata.version}
-- **Framework:** {project_metadata.framework}
-- **Architecture:** {project_metadata.architecture}
-- **Entry Point:** {project_metadata.entry_point}
-
-**Auto-Generated API Docs:**
-{if api_docs detected:}
-- ✅ {api_docs.type} detected at {api_docs.location}
-{else:}
-- ❌ No auto-generated API docs detected
-
-**Existing Documentation Assets:**
-- CONTRIBUTING.md: {✅ YES | ❌ NO}
-- .env.example: {✅ YES | ❌ NO}
-```
-
----
-
-### Phase 2: Directory Structure & Content Seeding
-
-**Goal:** Create hierarchical docs/ structure with seeded initial content
-
-**🚨 CRITICAL EXECUTION REQUIREMENT:**
-
-APO MUST use the **Write tool** to create documentation files in this phase.
-- Creating directories is NOT enough
-- Showing content templates is NOT enough
-- APO MUST execute `Write("docs/guides/getting-started.md", content)` commands
-- Minimum 4 files MUST be created: getting-started.md, api/README.md, architecture/overview.md, reference/README.md
-
-**Standard Directory Structure:**
-
-```
-docs/
-├── README.md (navigation - created in Phase 4)
-├── guides/           (How-to guides, tutorials)
-│   └── getting-started.md (seeded)
-├── api/              (API documentation)
-│   └── README.md (seeded with project context)
-├── architecture/     (Architecture diagrams, design docs)
-│   └── overview.md (auto-generated from codebase)
-├── reference/        (Reference documentation)
-│   └── README.md (seeded with CLI commands, env vars)
-└── images/           (Images, diagrams, screenshots)
-```
-
-**Step 1: Create Missing Directories**
-
-```javascript
-required_dirs = [
-  "docs/guides",
-  "docs/api",
-  "docs/architecture",
-  "docs/reference",
-  "docs/images"
-]
-
-created_dirs = []
-
-for each dir in required_dirs:
-  if not exists(dir):
-    create_directory(dir)
-    created_dirs.push(dir)
-```
-
-**Step 2: Seed docs/guides/ Content (ENHANCEMENT 2)**
-
-**CRITICAL: Create useful starter guides based on project type, not empty placeholders**
-
-**✅ APO MUST:**
-1. USE Write tool to create docs/guides/getting-started.md with project-specific content
-2. USE Write tool to create framework-specific guides (if applicable)
-3. Content MUST be based on actual project metadata from Phase 1
-4. NO generic placeholders - use real project name, version, dependencies
-
-**EXECUTION REQUIRED:**
-```javascript
-// APO MUST execute these Write commands:
-
-// 1. Create getting-started.md
-Write("docs/guides/getting-started.md", getting_started_content);
-
-// 2. Create framework-specific guide (if detected)
-if (framework === "Express" || framework === "NestJS") {
-  Write("docs/guides/api-development.md", api_dev_content);
-}
-if (framework === "React" || framework === "Next.js") {
-  Write("docs/guides/component-development.md", component_dev_content);
-}
-if (framework === "Django" || framework === "Flask") {
-  Write("docs/guides/django-development.md", django_dev_content);
-}
-```
-
-**CONTENT TEMPLATE for docs/guides/getting-started.md:**
-
-```markdown
-
-# Getting Started with {{PROJECT_NAME}}
-
-**Version:** {{VERSION}}
-**Last Updated:** {{CURRENT_DATE}}
-
-## Overview
-
-{project_metadata.description or "This guide will help you get started with {{PROJECT_NAME}}."}
-
-## Prerequisites
-
-{if project_metadata.type === "Node.js":}
-- Node.js ≥ {extract from package.json engines or "16.0.0"}
-- npm or yarn package manager
-
-{if project_metadata.type === "Python":}
-- Python ≥ {extract from pyproject.toml or "3.8"}
-- pip package manager
-
-{if project_metadata.type === "Rust":}
-- Rust {extract from Cargo.toml or "latest stable"}
-- Cargo build tool
-
-{if project_metadata.type === "Flutter":}
-- Flutter SDK {extract from pubspec.yaml or "latest"}
-- Dart SDK
-
-## Installation
-
-{if project_metadata.type === "Node.js":}
-```bash
-# Clone the repository
-git clone {repository URL from package.json or placeholder}
-cd {{PROJECT_NAME}}
-
-# Install dependencies
-npm install
-
-# Run development server
-npm run dev
-```
-
-{if project_metadata.type === "Python":}
-```bash
-# Clone the repository
-git clone {repository URL}
-cd {{PROJECT_NAME}}
-
-# Create virtual environment
-python -m venv venv
-source venv/bin/activate  # On Windows: venv\Scripts\activate
-
-# Install dependencies
-pip install -r requirements.txt
-
-# Run application
-python main.py
-```
-
-{if project_metadata.type === "Rust":}
-```bash
-# Clone the repository
-git clone {repository URL}
-cd {{PROJECT_NAME}}
-
-# Build project
-cargo build
-
-# Run project
-cargo run
-```
-
-## Project Structure
-
-```
-{actual src/ directory structure from Phase 1 scan}
-```
-
-## Next Steps
-
-- [API Documentation](../api/) - Learn about available APIs
-- [Architecture Overview](../architecture/overview.md) - Understand system design
-{if has CONTRIBUTING.md:}
-- [Contributing Guide](../../CONTRIBUTING.md) - Contribute to the project
-
-## Common Issues
-
-{if project_metadata.type === "Node.js":}
-### "Module not found" errors
-- Ensure you've run `npm install`
-- Clear node_modules and reinstall: `rm -rf node_modules && npm install`
-
-{if project_metadata.type === "Python":}
-### Import errors
-- Ensure virtual environment is activated
-- Reinstall dependencies: `pip install -r requirements.txt`
-
-## Support
-
-{Placeholder for support information}
-- GitHub Issues: [repository]/issues
-- Documentation: [docs/](../)
-```
-
-**Create Framework-Specific Guides (ENHANCEMENT 10)**
-
-```markdown
-{if framework === "Express":}
-### docs/guides/api-development.md
-
-# API Development Guide
-
-## Creating Routes
-
-```javascript
-// src/routes/example.js
-const express = require('express');
-const router = express.Router();
-
-router.get('/example', (req, res) => {
-  res.json({ message: 'Example endpoint' });
-});
-
-module.exports = router;
-```
-
-## Middleware
-
-{Examples based on detected middleware patterns in codebase}
-
-## Error Handling
-
-{if error handling patterns detected, show them}
-
-{if framework === "React":}
-### docs/guides/component-development.md
-
-# Component Development Guide
-
-## Component Structure
-
-```jsx
-// Functional Component Example
-import React from 'react';
-
-export const ExampleComponent = ({ prop1, prop2 }) => {
-  return (
-    <div>
-      {/* Component content */}
-    </div>
-  );
-};
-```
-
-## State Management
-
-{if Redux detected: show Redux patterns}
-{if Context API detected: show Context patterns}
-
-{if framework === "Django":}
-### docs/guides/django-development.md
-
-# Django Development Guide
-
-## Creating Apps
-
-```bash
-python manage.py startapp myapp
-```
-
-## Models and Migrations
-
-{Examples of model creation and migration workflow}
-
-## Admin Panel
-
-{Django admin setup instructions}
-```
-
-**Step 3: Seed docs/api/ Content (ENHANCEMENT 2 + 8)**
-
-**✅ APO MUST:**
-1. USE Write tool to create docs/api/README.md
-2. Include links to auto-generated API docs if detected in Phase 1
-3. If no auto-generated docs, create basic API documentation structure
-
-**EXECUTION REQUIRED:**
-```javascript
-// APO MUST execute this Write command:
-Write("docs/api/README.md", api_readme_content);
-```
-
-**CONTENT TEMPLATE for docs/api/README.md:**
-
-```markdown
-
-# API Documentation
-
-{if project_metadata.api_docs (TypeDoc/Rustdoc/etc):}
-
-**Auto-Generated API Reference:** [{api_docs.type}]({api_docs.entry})
-
-Full API documentation is available in the auto-generated {api_docs.type} documentation.
-
-{else if framework matches API framework (Express, FastAPI, etc):}
-
-**{project_metadata.name}** API documentation.
-
-## Endpoints
-
-{if Express and routes detected:}
-### Available Routes
-
-{scan src/ for route files and list endpoints}
-
-- `GET /api/example` - Example endpoint
-{list actual detected routes from codebase}
-
-## Authentication
-
-{if authentication patterns detected, document them}
-
-## Request/Response Format
-
-All API responses follow this format:
-
-```json
-{
-  "success": true,
-  "data": {},
-  "error": null
-}
-```
-
-{else:}
-
-API documentation for {{PROJECT_NAME}}.
-
-## Overview
-
-{Framework-specific API documentation guidance}
-
-{if project_metadata.type === "Node.js":}
-Consider using tools like:
-- Swagger/OpenAPI for REST APIs
-- GraphQL documentation for GraphQL APIs
-- TypeDoc for TypeScript API reference
-
-{if project_metadata.type === "Python":}
-Consider using tools like:
-- Sphinx for Python API reference
-- FastAPI automatic documentation (available at /docs)
-- Django REST Framework browsable API
-```
-
-**Step 4: Auto-Generate docs/architecture/overview.md (ENHANCEMENT 4)**
-
-**CRITICAL: Create real architecture documentation from codebase analysis**
-
-**✅ APO MUST:**
-1. USE Write tool to create docs/architecture/overview.md
-2. Content MUST be auto-generated from Phase 1 codebase analysis
-3. Include actual directory structure, detected patterns, entry points
-4. NO generic templates - use real project metadata
-
-**EXECUTION REQUIRED:**
-```javascript
-// APO MUST execute this Write command:
-Write("docs/architecture/overview.md", architecture_overview_content);
-```
-
-**CONTENT TEMPLATE for docs/architecture/overview.md:**
-
-```markdown
-
-# Architecture Overview
-
-**Project:** {{PROJECT_NAME}}
-**Type:** {project_metadata.type}
-**Framework:** {project_metadata.framework}
-**Version:** {project_metadata.version}
-**Last Updated:** {{CURRENT_DATE}}
-
-## System Overview
-
-{project_metadata.description}
-
-## Technology Stack
-
-**Runtime/Language:** {project_metadata.type} {version}
-**Framework:** {project_metadata.framework}
-
-{if project_metadata.type === "Node.js":}
-**Package Manager:** npm/yarn
-**Build Tool:** {detect from package.json scripts}
-
-{if project_metadata.dependencies.length > 0:}
-**Key Dependencies:**
-{list major dependencies from package.json}
-- {dependency}: {purpose detected or version}
-
-{if database detected:}
-**Database:** {detected database from dependencies}
-
-## Architecture Pattern
-
-**Pattern:** {project_metadata.architecture}
-
-{if architecture === "MVC":}
-This project follows the Model-View-Controller (MVC) architectural pattern:
-- **Models:** Data structures and business logic
-- **Views:** Presentation layer
-- **Controllers:** Request handling and coordination
-
-{if architecture === "React Component Architecture":}
-This project follows React's component-based architecture:
-- **Components:** Reusable UI building blocks
-- **Pages:** Top-level route components
-- **Hooks:** Custom React hooks for shared logic
-- **Context:** Global state management
-
-{if architecture === "Service Layer Architecture":}
-This project uses a service-oriented architecture:
-- **Services:** Business logic layer
-- **Repositories:** Data access layer
-- **Controllers:** API endpoint handlers
-
-## Directory Structure
-
-```
-{actual src/ directory structure from Phase 1 analysis}
-```
-
-**Key Directories:**
-{for each major directory in src/:}
-- **{directory}:** {purpose based on name/content}
-
-## Entry Points
-
-{if project_metadata.entry_point:}
-**Main Entry:** {entry_point}
-
-{if CLI commands detected from package.json:}
-**CLI Commands:**
-{list npm scripts or CLI commands}
-- `{command}`: {purpose}
-
-## Data Flow
-
-{if architecture pattern is recognized, describe typical data flow}
-
-{if API framework:}
-1. Request received at endpoint
-2. Middleware processing
-3. Controller handles request
-4. Service layer executes business logic
-5. Repository accesses data
-6. Response sent to client
-
-## Configuration
-
-{if .env.example exists:}
-**Environment Variables:** See [.env.example](../../.env.example)
-
-{list detected config files:}
-**Configuration Files:**
-- {config file}: {purpose}
-
-## Build & Deployment
-
-{from package.json scripts or build system:}
-**Build Command:** `{build command}`
-**Development:** `{dev command}`
-**Production:** `{start command}`
-
-## Architecture Diagrams
-
-*Architecture diagrams can be added to the [images/](../images/) directory and linked here.*
-
-Recommended diagrams:
-- System architecture diagram
-- Component interaction diagram
-- Data flow diagram
-- Deployment architecture
-
-## Design Decisions
-
-{if ADR files detected, link to them}
-
-Key architectural decisions are documented in:
-- [Architecture Decision Records](adr/) - ADRs documenting major technical decisions
-
-## Performance Considerations
-
-{Framework-specific performance guidance}
-
-## Security Considerations
-
-{Framework-specific security guidance}
-
----
-
-For detailed API documentation, see [../api/](../api/).
-```
-
-**Step 5: Seed docs/reference/ Content (ENHANCEMENT 2)**
-
-**✅ APO MUST:**
-1. USE Write tool to create docs/reference/README.md
-2. Include actual CLI commands from package.json scripts
-3. Document environment variables if .env.example exists
-4. List configuration options if detected
-
-**EXECUTION REQUIRED:**
-```javascript
-// APO MUST execute this Write command:
-Write("docs/reference/README.md", reference_readme_content);
-```
-
-**CONTENT TEMPLATE for docs/reference/README.md:**
-
-```markdown
-
-# Reference Documentation
-
-Quick reference materials for {{PROJECT_NAME}}.
-
-## CLI Commands
-
-{if package.json scripts detected:}
-### npm Scripts
-
-{for each script in package.json.scripts:}
-- **`npm run {script}`** - {infer purpose from script name or command}
-
-{if Makefile detected:}
-### Make Commands
-
-{for each target in Makefile:}
-- **`make {target}`** - {purpose}
-
-## Environment Variables
-
-{if .env.example exists:}
-See [.env.example](../../.env.example) for all available environment variables.
-
-**Required Variables:**
-{parse .env.example and list required vars}
-- `{VAR_NAME}` - {purpose}
-
-## Configuration
-
-{list detected config files and their purpose}
-
-## API Reference
-
-{if auto-generated API docs:}
-See [API Documentation](../api/) for complete API reference.
-
-## Dependencies
-
-**Production Dependencies:** {count}
-{list major production dependencies}
-
-**Development Dependencies:** {count}
-{list major dev dependencies}
-
-## Glossary
-
-{Project-specific terminology}
-```
-
-**Step 6: Migrate CONTRIBUTING.md to Reference (if exists)**
-
-```bash
-if exists("CONTRIBUTING.md"):
-  # Don't move the file, but reference it from docs/reference/
-  # Add link in docs/reference/README.md
-```
-
-**Step 7: Create Category README Files**
-
-For each category, create README.md that lists actual content:
-
-```markdown
-### docs/guides/README.md
-
-# Guides
-
-User guides and tutorials for {{PROJECT_NAME}}.
-
-## Available Guides
-
-{if getting-started.md created:}
-- [Getting Started](getting-started.md) - Quick start guide for new users
-
-{if framework-specific guide created:}
-- [{Framework} Development](....md) - {Framework}-specific development guide
-
-{if scattered docs migrated to guides/:}
-{list migrated files}
-
-## Planned Guides
-
-*Additional guides can be added to this directory. Common guide topics include:*
-- Deployment guide
-- Testing guide
-- Troubleshooting guide
-- Advanced features guide
-
-## Contributing
-
-To add a new guide:
-1. Create a new .md file in this directory
-2. Follow the guide template format:
-   - Clear title and objective
-   - Prerequisites section
-   - Step-by-step instructions
-   - Expected outcomes
-   - Troubleshooting tips
-3. Update this README with a link to your guide
-
----
-
-See [../README.md](../README.md) for complete documentation index.
-```
-
-```markdown
-### docs/api/README.md
-
-{Content from Step 3 - already seeded with project-specific info}
-```
-
-```markdown
-### docs/architecture/README.md
-
-# Architecture Documentation
-
-System architecture and design documentation for {{PROJECT_NAME}}.
-
-## Architecture Overview
-
-**Main Document:** [Architecture Overview](overview.md) - Complete system architecture
-
-{if ADR directory exists or should be created:}
-## Architecture Decision Records (ADRs)
-
-*Architecture Decision Records document significant architectural decisions made during development.*
-
-{if ADR files exist:}
-{list ADR files}
-
-{else:}
-ADRs can be added to the `adr/` subdirectory following the [ADR template format](https://github.com/joelparkerhenderson/architecture-decision-record).
-
-## Architecture Diagrams
-
-{if images/ has architecture diagrams:}
-{list diagram files}
-
-{else:}
-*Architecture diagrams can be added to [../images/](../images/) directory.*
-
-Recommended diagrams:
-- System architecture diagram
-- Component interaction diagram
-- Data flow diagram
-- Deployment architecture
-
-## Technology Stack
-
-See [Architecture Overview](overview.md#technology-stack) for complete technology stack details.
-
----
-
-See [../README.md](../README.md) for complete documentation index.
-```
-
-```markdown
-### docs/reference/README.md
-
-{Content from Step 5 - already seeded with CLI commands, env vars}
-```
-
-**Phase 2 Execution Summary:**
-
-**✅ MANDATORY FILE CREATIONS:**
-
-APO MUST have executed Write tool for these files (minimum required):
-1. ✅ docs/guides/getting-started.md
-2. ✅ docs/api/README.md
-3. ✅ docs/architecture/overview.md
-4. ✅ docs/reference/README.md
-
-**Optional (based on detected framework):**
-- docs/guides/{framework}-development.md (if Express/React/Django/etc detected)
-
-**VERIFICATION:**
-
-If APO did NOT create these files using Write tool, APO has FAILED Phase 2.
-
-**APO Output:**
-
-```markdown
-=== PHASE 2: DIRECTORY STRUCTURE & CONTENT SEEDING ===
-
-**Directories Created:** {created_dirs.length}
-- ✅ docs/guides/
-- ✅ docs/api/
-- ✅ docs/architecture/
-- ✅ docs/reference/
-- ✅ docs/images/
-
-**Files Created with Write Tool:** {count} files
-
-**VERIFICATION - Files Created:**
-
-**Guides:**
-- ✅ docs/guides/getting-started.md ({line_count} lines)
-{if framework-specific guide created:}
-- ✅ docs/guides/{framework}-development.md ({line_count} lines)
-
-**API Documentation:**
-- ✅ docs/api/README.md ({line_count} lines)
-{if TypeDoc integrated:}
-- ✅ Integrated {api_docs.type} documentation
-
-**Architecture:**
-- ✅ docs/architecture/overview.md ({line_count} lines) - AUTO-GENERATED from codebase
-{if ADR directory created:}
-- ✅ docs/architecture/adr/ directory created
-
-**Reference:**
-- ✅ docs/reference/README.md ({line_count} lines)
-
-**Category READMEs:** 4 files
-- ✅ docs/guides/README.md
-- ✅ docs/api/README.md
-- ✅ docs/architecture/README.md
-- ✅ docs/reference/README.md
-
-**Project Context Used:**
-- Type: {project_metadata.type}
-- Framework: {project_metadata.framework}
-- Architecture: {project_metadata.architecture}
-- Dependencies: {major_deps_count} major dependencies documented
-```
-
----
-
-### Phase 3: Scattered Documentation Migration
-
-**Goal:** Migrate scattered .md files into organized docs/ structure
-
-**CRITICAL: Only migrate orphaned documentation, preserve Trinity infrastructure**
-
-**Step 1: Review Migration Candidates**
-
-```javascript
-// From Phase 1 Step 4 - scattered_docs array
-
-migration_plan = []
-
-for each doc in scattered_docs:
-  // Verify file still exists and should be migrated
-  if exists(doc.file) and not is_excluded(doc.file):
-    migration_plan.push({
-      source: doc.file,
-      destination: doc.suggested_category + extract_filename(doc.file),
-      action: "MOVE"
-    })
-```
-
-**Step 2: Execute Migration**
-
-```bash
-migrated_files = []
-migration_errors = []
-
-for each item in migration_plan:
-  try:
-    # Create destination directory if needed
-    ensure_directory_exists(item.destination)
-
-    # Move file to new location
-    move_file(item.source, item.destination)
-
-    migrated_files.push(item)
-  catch error:
-    migration_errors.push({item, error})
-```
-
-**Step 3: Update Internal Links (ENHANCEMENT 5 - partial)**
-
-```bash
-# After migration, update links in migrated files
-for each migrated_file in migrated_files:
-  content = read(migrated_file.destination)
-
-  # Update relative links that may have broken
-  updated_content = update_relative_links(content, migrated_file.source, migrated_file.destination)
-
-  if updated_content != content:
-    write(migrated_file.destination, updated_content)
-```
-
-**Step 4: Update Category READMEs**
-
-```bash
-# Add migrated files to appropriate category READMEs
-for each migrated_file in migrated_files:
-  category_readme = get_category_readme(migrated_file.destination)
-
-  # Add link to migrated file in category README
-  append_to_section(category_readme, "Available {Category}", link_to_file)
-```
-
-**APO Output:**
-
-```markdown
-=== PHASE 3: SCATTERED DOCUMENTATION MIGRATION ===
-
-**Migration Summary:**
-- Files migrated: {migrated_files.length}
-- Migration errors: {migration_errors.length}
-
-**Migrated Files:**
-{for each migrated:}
-- ✅ {source} → {destination}
-
-{if migration_errors.length > 0:}
-**Migration Errors:**
-{for each error:}
-- ❌ {item.source}: {error.message}
-
-**Files NOT Migrated (Preserved):**
-- Trinity infrastructure (trinity/**): {count} files
-- CLAUDE.md files: {count} files
-- Root standards (README, CHANGELOG, etc.): {count} files
-- Technical source READMEs (src/README.md, etc.): {count} files
-
-**Link Updates:** {count} files with updated links
-
-**Category Updates:**
-{for each category:}
-- docs/{category}/README.md: Added {count} migrated files
-```
-
----
-
-### Phase 4: Link Validation & Navigation Creation
-
-**Goal:** Validate all documentation links, fix broken links, and create comprehensive navigation
-
-**Step 1: Extract All Links from Documentation (ENHANCEMENT 5)**
-
-```bash
-all_docs_files = glob("docs/**/*.md")
-all_links = []
-
-for each doc_file in all_docs_files:
-  content = read(doc_file)
-
-  # Extract markdown links [text](path)
-  links = extract_markdown_links(content)
-
-  for each link in links:
-    all_links.push({
-      source_file: doc_file,
-      link_text: link.text,
-      link_path: link.path,
-      line_number: link.line
-    })
-```
-
-**Step 2: Validate Links**
-
-```bash
-broken_links = []
-valid_links = []
-
-for each link in all_links:
-  # Skip external URLs (http://, https://)
-  if is_external_url(link.link_path):
-    continue
-
-  # Resolve relative path
-  resolved_path = resolve_path(link.source_file, link.link_path)
-
-  # Check if linked file exists
-  if exists(resolved_path):
-    valid_links.push(link)
-  else:
-    broken_links.push({
-      link: link,
-      resolved_path: resolved_path,
-      error: "File not found"
-    })
-```
-
-**Step 3: Fix Broken Links**
-
-```bash
-fixed_links = []
-unfixable_links = []
-
-for each broken_link in broken_links:
-  # Try to find the correct path
-  filename = extract_filename(broken_link.resolved_path)
-
-  # Search for file in docs/
-  possible_matches = glob(f"docs/**/{filename}")
-
-  if possible_matches.length === 1:
-    # Found unique match - fix the link
-    correct_path = calculate_relative_path(
-      broken_link.link.source_file,
-      possible_matches[0]
-    )
-
-    # Update link in source file
-    update_link_in_file(
-      broken_link.link.source_file,
-      broken_link.link.link_path,
-      correct_path
-    )
-
-    fixed_links.push({broken_link, correct_path})
-
-  else if possible_matches.length > 1:
-    # Multiple matches - can't auto-fix
-    unfixable_links.push({
-      broken_link,
-      reason: "Multiple possible matches",
-      matches: possible_matches
-    })
-
-  else:
-    # No matches - file doesn't exist
-    unfixable_links.push({
-      broken_link,
-      reason: "File not found in docs/"
-    })
-```
-
-**Step 4: Generate docs/README.md Navigation**
-
-```markdown
-### docs/README.md
-
-# Documentation
-
-Comprehensive documentation for {{PROJECT_NAME}}.
-
-## Documentation Structure
-
-This directory contains organized project documentation:
-
-- **[Guides](guides/)** - How-to guides and tutorials
-- **[API](api/)** - API reference documentation
-{if api_docs detected:}
-  - [{api_docs.type} Reference]({api_docs.entry}) - Auto-generated API documentation
-- **[Architecture](architecture/)** - System architecture and design decisions
-- **[Reference](reference/)** - Quick references and command guides
-
-## Quick Start
-
-New to {{PROJECT_NAME}}? Start here:
-
-1. **[Getting Started Guide](guides/getting-started.md)** - Installation and setup
-{if framework-specific guide exists:}
-2. **[{Framework} Development](guides/{framework}-development.md)** - Framework-specific development guide
-3. **[Architecture Overview](architecture/overview.md)** - Understand the system design
-{if API documentation exists:}
-4. **[API Documentation](api/)** - Explore available APIs
-
-## Documentation Categories
-
-### Guides
-
-{list actual guide files from docs/guides/, exclude README.md}
-- [Getting Started](guides/getting-started.md) - Quick start for new users
-{for each guide file:}
-- [{title}]({path}) - {extract description from file}
-
-{if guides/ is empty or only has README:}
-*No additional guides available yet. See [guides/README.md](guides/README.md) for planned guides.*
-
-### API Documentation
-
-{if TypeDoc/Rustdoc/etc detected:}
-**[{api_docs.type} Reference]({api_docs.entry})** - Auto-generated API documentation
-
-{list actual API doc files from docs/api/, exclude README.md}
-{for each API doc:}
-- [{title}]({path}) - {description}
-
-{if api/ has only README or TypeDoc:}
-See [api/README.md](api/) for API overview and documentation links.
-
-### Architecture
-
-{list actual architecture files from docs/architecture/, exclude README.md}
-- [Architecture Overview](architecture/overview.md) - System design and technology stack
-
-{if ADR files exist:}
-**Architecture Decision Records:**
-{for each ADR:}
-- [{ADR title}]({path}) - {decision summary}
-
-{if architecture diagrams exist in images/:}
-**Architecture Diagrams:**
-{for each diagram:}
-- [{diagram name}]({path})
-
-### Reference
-
-{list actual reference files from docs/reference/, exclude README.md}
-- [Reference Documentation](reference/README.md) - CLI commands, environment variables, glossary
-
-## Documentation Standards
-
-- All documentation is in Markdown format
-- Images are stored in `images/` directory
-- Each category has its own README for navigation
-{if ADR directory exists:}
-- Architecture decisions are documented using ADR format
-
-## Contributing to Documentation
-
-{if CONTRIBUTING.md exists:}
-See [CONTRIBUTING.md](../CONTRIBUTING.md) for documentation contribution guidelines.
-
-{else:}
-To contribute to documentation:
-1. Follow the existing structure (guides/, api/, architecture/, reference/)
-2. Use clear, concise Markdown
-3. Include code examples where applicable
-4. Update category README files when adding new documentation
-5. Validate all links before submitting
-
-## Documentation Index
-
-### All Documentation Files
-
-{alphabetical index of all .md files in docs/, organized by category}
-
-**Guides ({count}):**
-{for each guide, alphabetically:}
-- [{title}]({path})
-
-**API Documentation ({count}):**
-{for each API doc, alphabetically:}
-- [{title}]({path})
-
-**Architecture ({count}):**
-{for each architecture doc, alphabetically:}
-- [{title}]({path})
-
-**Reference ({count}):**
-{for each reference doc, alphabetically:}
-- [{title}]({path})
-
----
-
-**Documentation Coverage:** {coverage_score}/100 (see [Organization Report](../trinity/reports/DOCS-ORGANIZATION-{date}.md))
-
-*Last updated: {{CURRENT_DATE}}*
-```
-
-**Step 5: Build Complete Documentation Index**
-
-```javascript
-all_docs = []
-
-// Scan all subdirectories
-for each category in ["guides", "api", "architecture", "reference"]:
-  files = glob(f"docs/{category}/**/*.md")
-  for each file in files:
-    if file != "README.md":
-      all_docs.push({
-        title: extract_title_from_file(file),
-        path: file,
-        category: category,
-        description: extract_description(file)
-      })
-
-// Sort alphabetically
-all_docs.sort_by_title()
-```
-
-**APO Output:**
-
-```markdown
-=== PHASE 4: LINK VALIDATION & NAVIGATION CREATION ===
-
-**Link Validation:**
-- Total links found: {all_links.length}
-- Valid links: {valid_links.length}
-- Broken links: {broken_links.length}
-- Fixed links: {fixed_links.length}
-- Unfixable links: {unfixable_links.length}
-
-**Broken Links Fixed:**
-{for each fixed_link:}
-- ✅ {source_file}: {old_path} → {new_path}
-
-{if unfixable_links.length > 0:}
-**Unfixable Links (Manual Review Required):**
-{for each unfixable:}
-- ⚠️ {source_file}:{line_number}: [{link_text}]({link_path})
-  - Reason: {reason}
-  {if multiple matches:}
-  - Possible matches: {list matches}
-
-**Navigation Creation:**
-- ✅ docs/README.md created ({line_count} lines)
-
-**Documentation Index:**
-- Total files indexed: {all_docs.length}
-- Guides: {guides_count}
-- API docs: {api_count}
-- Architecture docs: {architecture_count}
-- Reference docs: {reference_count}
-
-**Quick Links:** {count} essential documentation files highlighted
-```
-
----
-
-### Phase 5: Organization Report & Coverage Metrics
-
-**APO Generates:** `trinity/reports/DOCS-ORGANIZATION-{date}.md`
-
-**Step 1: Calculate Documentation Coverage Metrics (ENHANCEMENT 9)**
-
-```javascript
-coverage_metrics = {
-  structure: 0,
-  content: 0,
-  navigation: 0,
-  total: 0
-}
-
-// Structure score (30 points)
-structure_score = 0
-if exists("docs/guides/"): structure_score += 6
-if exists("docs/api/"): structure_score += 6
-if exists("docs/architecture/"): structure_score += 6
-if exists("docs/reference/"): structure_score += 6
-if exists("docs/images/"): structure_score += 6
-
-coverage_metrics.structure = structure_score
-
-// Content score (50 points)
-content_score = 0
-
-// Guides content (15 points)
-guides_files = glob("docs/guides/*.md", exclude="README.md")
-if guides_files.length >= 1: content_score += 5  // Getting started exists
-if guides_files.length >= 2: content_score += 5  // Framework guide exists
-if guides_files.length >= 3: content_score += 5  // Additional guides
-
-// API documentation (15 points)
-if api_docs detected or exists("docs/api/*.md"): content_score += 15
-
-// Architecture documentation (15 points)
-if exists("docs/architecture/overview.md"): content_score += 10
-if exists("docs/architecture/adr/*"): content_score += 5
-
-// Reference documentation (5 points)
-if exists("docs/reference/README.md") and has_content: content_score += 5
-
-coverage_metrics.content = content_score
-
-// Navigation score (20 points)
-navigation_score = 0
-if exists("docs/README.md"): navigation_score += 10
-if all category READMEs exist: navigation_score += 10
-
-coverage_metrics.navigation = navigation_score
-
-// Total coverage
-coverage_metrics.total = structure_score + content_score + navigation_score
-
-// Grade
-if coverage_metrics.total >= 90: grade = "A (Excellent)"
-else if coverage_metrics.total >= 80: grade = "B (Good)"
-else if coverage_metrics.total >= 70: grade = "C (Fair)"
-else if coverage_metrics.total >= 60: grade = "D (Needs Improvement)"
-else: grade = "F (Poor)"
-```
-
-**Step 2: Generate Actionable Recommendations for Empty Categories (ENHANCEMENT 7)**
-
-```javascript
-recommendations = []
-
-// Check guides/
-guides_count = count_md_files("docs/guides/", exclude="README.md")
-if guides_count === 0:
-  recommendations.push({
-    category: "guides",
-    priority: "HIGH",
-    items: [
-      "Create Getting Started guide with installation steps",
-      "Document common workflows and use cases",
-      "Add troubleshooting guide for common issues"
-    ]
-  })
-else if guides_count < 3:
-  recommendations.push({
-    category: "guides",
-    priority: "MEDIUM",
-    items: [
-      "Add deployment guide",
-      "Create testing guide",
-      "Document advanced features"
-    ]
-  })
-
-// Check architecture/
-arch_count = count_md_files("docs/architecture/", exclude="README.md")
-if arch_count === 0 or not exists("docs/architecture/overview.md"):
-  recommendations.push({
-    category: "architecture",
-    priority: "HIGH",
-    items: [
-      "✅ AUTO-GENERATED: Architecture overview created",
-      "Add system architecture diagram to images/",
-      "Create component interaction diagram",
-      "Document architecture decision records (ADRs)"
-    ]
-  })
-
-// Check API documentation
-if not api_docs and api_count === 0:
-  recommendations.push({
-    category: "api",
-    priority: "MEDIUM",
-    items: [
-      "Generate API documentation using TypeDoc/Rustdoc/Sphinx",
-      "Document API endpoints and request/response formats",
-      "Add API authentication and authorization guide"
-    ]
-  })
-
-// Check for duplicates
-if duplicates.length > 0:
-  recommendations.push({
-    category: "quality",
-    priority: "MEDIUM",
-    items: [
-      f"Review {duplicates.length} potential duplicate documentation files",
-      "Consolidate overlapping content",
-      "Remove or rename duplicate files"
-    ]
-  })
-
-// Check for broken links
-if unfixable_links.length > 0:
-  recommendations.push({
-    category: "quality",
-    priority: "HIGH",
-    items: [
-      f"Fix {unfixable_links.length} broken documentation links (see Phase 4 report)"
-    ]
-  })
-```
-
-**Required Report Structure:**
-
-```markdown
-# docs/ Organization Report
-
-**Project:** {{PROJECT_NAME}}
-**Organization Date:** {date}
-**Organizer:** APO (Documentation Specialist)
-**Command:** /trinity-docs
-
----
-
-## Executive Summary
-
-**docs/ Structure:** {✅ ORGANIZED | ⚠️ PARTIALLY ORGANIZED}
-**Navigation:** {✅ COMPLETE | ⚠️ PARTIAL}
-**Categories:** 5 categories (guides, api, architecture, reference, images)
-**Content Created:** {count} files with seeded content
-**Files Migrated:** {migrated_files.length} scattered docs organized
-**Links Fixed:** {fixed_links.length} broken links repaired
-
-**Documentation Coverage:** {coverage_metrics.total}/100 - Grade: {grade}
-
-**COMMAND EXECUTION STATUS:** {✅ SUCCESS | ⚠️ PARTIAL SUCCESS}
-
----
-
-## Documentation Coverage Breakdown
-
-**Overall Score:** {coverage_metrics.total}/100 ({grade})
-
-**Structure (30 points):** {structure_score}/30
-- Directory hierarchy: {✅ COMPLETE | ⚠️ PARTIAL}
-- guides/: {✅ | ❌}
-- api/: {✅ | ❌}
-- architecture/: {✅ | ❌}
-- reference/: {✅ | ❌}
-- images/: {✅ | ❌}
-
-**Content (50 points):** {content_score}/50
-- Guides: {guides_score}/15 {✅ | ⚠️ | ❌}
-  - Getting started: {✅ CREATED | ❌ MISSING}
-  - Framework guide: {✅ CREATED | ❌ MISSING}
-  - Additional guides: {count}
-- API Documentation: {api_score}/15 {✅ | ⚠️ | ❌}
-  - Auto-generated docs: {✅ INTEGRATED | ❌ NONE}
-  - Manual API docs: {count} files
-- Architecture: {arch_score}/15 {✅ | ⚠️ | ❌}
-  - Overview: {✅ AUTO-GENERATED | ❌ MISSING}
-  - ADRs: {count} records
-  - Diagrams: {count} diagrams
-- Reference: {ref_score}/5 {✅ | ❌}
-  - CLI/env reference: {✅ CREATED | ❌ MISSING}
-
-**Navigation (20 points):** {navigation_score}/20
-- docs/README.md: {✅ CREATED | ❌ MISSING}
-- Category READMEs: {count}/4
-- Documentation index: {✅ COMPLETE | ⚠️ PARTIAL}
-
----
-
-## Phase Execution Summary
-
-### Phase 1: Discovery & Codebase Analysis
-- **docs/ existed:** {✅ YES | ❌ NO (created)}
-- **Files found in docs/:** {count}
-- **Scattered docs found:** {scattered_docs.length} files
-- **Structure score:** {structure_score}/100
-- **Project type:** {project_metadata.type}
-- **Framework:** {project_metadata.framework}
-- **Architecture pattern:** {project_metadata.architecture}
-- **Auto-generated API docs:** {✅ {api_docs.type} | ❌ None}
-- **Duplicate docs:** {duplicates.length} potential duplicates
-
-### Phase 2: Directory Structure & Content Seeding
-- **Directories created:** {created_dirs.length}
-- **Content files created:** {count}
-  - Guides: {guides_created_count} ({getting-started, framework guide, etc.})
-  - API: {api_created_count}
-  - Architecture: {arch_created_count} (✅ AUTO-GENERATED overview)
-  - Reference: {ref_created_count}
-- **Category READMEs:** 4 created with project-specific content
-
-### Phase 3: Scattered Documentation Migration
-- **Files migrated:** {migrated_files.length}
-- **Migration errors:** {migration_errors.length}
-- **Links updated:** {count} files
-- **Files preserved:** {preserved_count} (Trinity infrastructure, CLAUDE.md, source READMEs)
-
-### Phase 4: Link Validation & Navigation
-- **docs/README.md:** ✅ CREATED ({line_count} lines)
-- **Total links validated:** {all_links.length}
-- **Broken links found:** {broken_links.length}
-- **Links fixed:** {fixed_links.length}
-- **Unfixable links:** {unfixable_links.length}
-- **Files indexed:** {all_docs.length}
-
----
-
-## Directory Structure
-
-**Before:**
-```
-{show actual before state from Phase 1}
-```
-
-**After:**
-```
-docs/
-├── README.md (navigation - {line_count} lines)
-├── guides/
-│   ├── README.md
-│   ├── getting-started.md (✅ CREATED - {line_count} lines)
-{if framework guide created:}
-│   ├── {framework}-development.md (✅ CREATED - {line_count} lines)
-{for each migrated guide:}
-│   └── {file} (migrated from {original_location})
-├── api/
-│   ├── README.md (seeded with {api_docs.type or "project context"})
-{if TypeDoc/etc:}
-│   ├── index.html ({api_docs.type})
-│   └── modules.html ({api_docs.type})
-{for each API doc file:}
-│   └── {file}
-├── architecture/
-│   ├── README.md
-│   ├── overview.md (✅ AUTO-GENERATED - {line_count} lines)
-{if ADR directory:}
-│   └── adr/
-{for each architecture file:}
-│       └── {file}
-├── reference/
-│   ├── README.md (seeded with CLI commands, env vars)
-{for each reference file:}
-│   └── {file}
-└── images/
-{for each image:}
-    └── {file}
-```
-
----
-
-## Files Created
-
-**Seeded Content ({count} files):**
-
-**Guides:**
-- ✅ **getting-started.md** ({line_count} lines) - Installation, setup, project structure
-{if framework guide:}
-- ✅ **{framework}-development.md** ({line_count} lines) - Framework-specific development guide
-
-**API Documentation:**
-- ✅ **api/README.md** ({line_count} lines) - Seeded with {api_docs.type or "project endpoints"}
-
-**Architecture:**
-- ✅ **architecture/overview.md** ({line_count} lines) - AUTO-GENERATED from codebase analysis
-  - Technology stack: {tech_stack}
-  - Architecture pattern: {architecture}
-  - Directory structure: Actual src/ layout
-  - Entry points: {entry_points}
-  - Configuration: {config_files}
-
-**Reference:**
-- ✅ **reference/README.md** ({line_count} lines) - CLI commands, environment variables
-
-**Category READMEs (4 files):**
-- ✅ guides/README.md - Lists all available guides
-- ✅ api/README.md - API overview and documentation links
-- ✅ architecture/README.md - Architecture docs and ADRs
-- ✅ reference/README.md - Quick reference materials
-
----
-
-## Files Migrated
-
-{if migrated_files.length > 0:}
-**Scattered Documentation Organized ({migrated_files.length} files):**
-
-{for each migrated file:}
-- ✅ `{source}` → `{destination}`
-
-**Files Preserved (NOT migrated):**
-- Trinity infrastructure: `trinity/**` ({count} files)
-- AI context files: `**/CLAUDE.md` ({count} files)
-- Root standards: `README.md`, `CHANGELOG.md`, `CONTRIBUTING.md`, etc.
-- Technical source READMEs: `src/README.md`, `tests/README.md`, etc.
-
-{else:}
-**No scattered documentation found** - All documentation was already in docs/ or properly located.
-
----
-
-## Navigation Structure
-
-**docs/README.md includes:**
-- ✅ Documentation structure overview
-- ✅ Quick start guide (links to getting-started.md)
-- ✅ Complete documentation index by category
-- ✅ Quick links to essential documentation
-{if api_docs:}
-- ✅ Link to {api_docs.type} auto-generated API reference
-- ✅ Documentation standards
-- ✅ Contributing guidelines
-
-**Category Navigation:**
-- ✅ guides/README.md: {guides_count} guides listed
-- ✅ api/README.md: API documentation overview
-- ✅ architecture/README.md: Architecture docs and ADRs
-- ✅ reference/README.md: CLI commands, env vars, glossary
-
----
-
-## Link Validation Results
-
-**Total Links Validated:** {all_links.length}
-- Valid links: {valid_links.length} ✅
-- Broken links found: {broken_links.length} ❌
-- Links auto-fixed: {fixed_links.length} ✅
-- Links requiring manual review: {unfixable_links.length} ⚠️
-
-{if fixed_links.length > 0:}
-**Auto-Fixed Links:**
-{for each fixed_link:}
-- ✅ {source_file}:{line_number}
-  - Old: `{old_path}` (broken)
-  - New: `{new_path}` (fixed)
-
-{if unfixable_links.length > 0:}
-**Links Requiring Manual Review:**
-{for each unfixable:}
-- ⚠️ {source_file}:{line_number}: [{link_text}]({link_path})
-  - Issue: {reason}
-  {if multiple matches:}
-  - Possible matches: {list matches}
-  - **Action Required:** Determine correct file and update link manually
-
----
-
-## Project Context Used
-
-**Codebase Analysis:**
-- **Project Type:** {project_metadata.type}
-- **Framework:** {project_metadata.framework}
-- **Version:** {project_metadata.version}
-- **Architecture Pattern:** {project_metadata.architecture}
-- **Entry Point:** {project_metadata.entry_point}
-- **Major Dependencies:** {major_deps_count} documented
-
-**Content Seeding:**
-- Getting Started guide: Framework-specific installation instructions
-- Architecture overview: Actual directory structure from `src/`
-- API documentation: {api_docs.type or "Endpoints detected"} from codebase
-- Reference: CLI commands from package.json scripts
-- Reference: Environment variables from .env.example
-
----
-
-## Duplicate Documentation Detected
-
-{if duplicates.length > 0:}
-**Potential Duplicates Found:** {duplicates.length} cases
-
-{for each duplicate:}
-- ⚠️ **{file1}** ↔ **{file2}**
-  - Similarity: {similarity_score}%
-  - Type: {title_similarity or content_similarity}
-  - **Recommendation:** Review and consolidate or clarify differences
-
-{else:}
-**No duplicate documentation detected** ✅
-
----
-
-## Completion Status
-
-**Required Elements:**
-- ✅ docs/ directory exists
-- ✅ Hierarchical structure (guides/, api/, architecture/, reference/, images/)
-- ✅ Seeded content in all categories
-- ✅ Auto-generated architecture overview
-- ✅ docs/README.md navigation
-- ✅ Category READMEs with actual content listings
-- ✅ Scattered documentation migrated ({migrated_files.length} files)
-- ✅ Documentation links validated ({fixed_links.length} fixed)
-{if api_docs:}
-- ✅ Auto-generated API docs integrated ({api_docs.type})
-
-**Documentation Coverage:** {coverage_metrics.total}/100 ({grade})
-
-{if coverage_metrics.total >= 70:}
-**SUCCESS Criteria:** All required elements present ✅
-
-{else:}
-**PARTIAL SUCCESS:** Core structure complete, content needs expansion ⚠️
-
----
-
-## Recommendations
-
-{if recommendations.length > 0:}
-
-{for each category_recommendation in recommendations:}
-### {category_recommendation.category} - Priority: {priority}
-
-{for each item in category_recommendation.items:}
-- {item}
-
-{else:}
-**No recommendations** - Documentation is comprehensive ✅
-
----
-
-## Next Steps
-
-### Immediate Actions
-
-{if unfixable_links.length > 0:}
-1. **Fix Broken Links** ({unfixable_links.length} links)
-   - Review links requiring manual attention (see Link Validation Results)
-
-{if duplicates.length > 0:}
-2. **Review Duplicate Documentation** ({duplicates.length} cases)
-   - Consolidate or clarify differences between similar files
-
-{if guides_count < 3:}
-3. **Expand Guides**
-   - Add deployment guide
-   - Create testing guide
-   - Document troubleshooting steps
-
-{if not api_docs and framework matches API framework:}
-4. **Generate API Documentation**
-   - Run TypeDoc/Rustdoc/Sphinx to generate API reference
-   - Document API endpoints and authentication
-
-### Future Enhancements
-
-{if not exists("docs/architecture/adr/"):}
-- **Architecture Decision Records**
-  - Start documenting architectural decisions using ADR format
-  - Create `docs/architecture/adr/` directory
-
-{if not has_architecture_diagrams:}
-- **Architecture Diagrams**
-  - Create system architecture diagram
-  - Add component interaction diagram
-  - Document deployment architecture
-
-- **Advanced Guides**
-  - Performance optimization guide
-  - Security best practices
-  - Debugging guide
-
----
-
-**Report Generated:** {timestamp}
-**Report Location:** trinity/reports/DOCS-ORGANIZATION-{date}.md
-
-**Documentation Status:** {✅ Production-Ready | ⚠️ Needs Content Expansion | ❌ Incomplete}
-```
-
-**APO Output:**
-
-```markdown
-=== PHASE 5: ORGANIZATION REPORT ===
-
-**Report Generated:** trinity/reports/DOCS-ORGANIZATION-{date}.md
-
-**Documentation Coverage Score:** {coverage_metrics.total}/100
-- Grade: {grade}
-- Structure: {structure_score}/30
-- Content: {content_score}/50
-- Navigation: {navigation_score}/20
-
-**Status:** {✅ SUCCESS | ⚠️ PARTIAL SUCCESS}
-
-**Key Achievements:**
-- ✅ {created_dirs.length} directories created
-- ✅ {content_files_created} files created with seeded content
-- ✅ Architecture overview auto-generated ({line_count} lines)
-- ✅ {migrated_files.length} scattered docs migrated
-- ✅ {fixed_links.length} broken links fixed
-- ✅ Complete navigation structure
-
-{if recommendations.length > 0:}
-**Recommendations:** {recommendations.length} categories
-- {list priority recommendations}
-
-**Report Location:** trinity/reports/DOCS-ORGANIZATION-{date}.md
-```
-
----
-
-## Success Criteria
-
-**Command succeeds when:**
-
-1. **docs/ Structure:** Hierarchical directories exist (guides/, api/, architecture/, reference/, images/)
-2. **Seeded Content:** Initial documentation created based on project type
-3. **Architecture Overview:** Auto-generated from codebase analysis
-4. **Navigation:** docs/README.md exists with complete index
-5. **Category READMEs:** Each category directory has README.md listing actual files
-6. **Migration:** Scattered documentation organized (if any found)
-7. **Link Validation:** Documentation links validated and fixed where possible
-8. **All Phases Complete:** 5/5 phases executed
-
-**Status Determination:**
-
-**✅ SUCCESS (Coverage ≥ 70/100):**
-- All required structure created
-- Content seeded in all categories
-- Architecture overview auto-generated
-- Navigation complete
-- Documentation coverage ≥ 70%
-
-**⚠️ PARTIAL SUCCESS (Coverage 40-69/100):**
-- Structure created
-- Some content seeded
-- Navigation exists
-- Manual content expansion needed
-
-**❌ NEEDS ATTENTION (Coverage < 40/100):**
-- Structural issues remain
-- Minimal content created
-- Re-run command or manual intervention needed
-
----
-
-## Post-Execution Checklist
-
-**After `/trinity-docs` completes, verify:**
-
-1. ✅ Check `trinity/reports/DOCS-ORGANIZATION-{date}.md` for full report
-2. ✅ Verify docs/README.md exists and navigation works
-3. ✅ Check docs/guides/getting-started.md was created
-4. ✅ Verify docs/architecture/overview.md was auto-generated
-5. ✅ Check all category directories exist with READMEs
-6. ✅ Review documentation coverage score (target: ≥70/100)
-7. ✅ Review recommendations section for next steps
-8. ✅ Fix any unfixable broken links (if reported)
-9. ✅ Review duplicate documentation (if reported)
-10. ✅ Check "COMMAND EXECUTION STATUS" = "✅ SUCCESS"
-
----
-
-## Framework-Specific Content Examples
-
-### Node.js/Express Projects
-
-**Guides Created:**
-- `getting-started.md`: npm install, project structure, npm run dev
-- `api-development.md`: Route creation, middleware, error handling
-
-**Architecture:**
-- Auto-detects Express routes, middleware patterns
-- Documents dependencies from package.json
-
-**Reference:**
-- CLI commands from package.json scripts
-- Environment variables from .env.example
-
-### Python/Django Projects
-
-**Guides Created:**
-- `getting-started.md`: pip install, virtual env, python manage.py runserver
-- `django-development.md`: App creation, models, migrations, admin
-
-**Architecture:**
-- Auto-detects Django apps, settings structure
-- Documents dependencies from requirements.txt or pyproject.toml
-
-### Rust Projects
-
-**Guides Created:**
-- `getting-started.md`: cargo build, cargo run
-- Crate-specific development guide
-
-**Architecture:**
-- Auto-detects from Cargo.toml
-- Documents crate dependencies
-
-### React Projects
-
-**Guides Created:**
-- `getting-started.md`: npm install, npm start
-- `component-development.md`: Component patterns, state management
-
-**Architecture:**
-- Auto-detects React components, hooks, context
-- Documents frontend architecture
-
----
-
-**Command Specification Version:** 3.0.0
-**Last Updated:** {{CURRENT_DATE}}
-**Enhancements:** Codebase analysis, content seeding, migration, auto-generation, link validation, coverage metrics, framework-specific content, duplicate detection, TypeDoc integration, actionable recommendations