docs: reorganize documentation conventions with progressive disclosure (MT-45)

[ai-cora]

Summary

• Reorganize documentation conventions into docs/conventions/documentation/ directory with progressive disclosure structure
• Add clear guidance for package vs core documentation organization
• Establish AGENTS.md as the industry standard for AI agent instructions
• Define file suffix conventions (-guide, -reference, -concepts)

Changes

Created 7 new files in docs/conventions/documentation/:

• README.md: Overview of documentation types with quick reference
• readme-guide.md: Templates for project, directory, and package READMEs
• root-documentation.md: Files allowed outside docs/ (AGENTS.md, SKILL.md, etc.)
• docs-structure.md: Category-based vs topic-based organization
• docs-structure-concepts.md: Diátaxis framework background
• command-usage.md: CLI help text and reference doc templates
• writing-style.md: Markdown, tone, formatting conventions

Updated:

• docs/conventions/README.md: Link to new documentation directory
• SKILL.md: Reference new documentation structure

Deleted:

• docs/conventions/documentation.md (content migrated)
• docs/conventions/documentation-organization.md (content migrated)

Key Decisions

1. Two documentation approaches:

   • Category-based (Diátaxis) for metool core and large projects
   • Topic-based with suffixes for metool packages (simpler default)

2. AGENTS.md is the industry standard for AI coding assistants (60k+ repos)

   • SKILL.md is for Claude Code skill definitions (different purpose)

3. docs/commands/ directory pattern for package command reference

   • Files named identically to binaries in bin/

Test plan

• All markdown files render correctly
• Links between documentation files work
• Review that SKILL.md doesn't duplicate content from docs/

🤖 Generated with Claude Code