diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..4976ea2
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,3 @@
+# Metool AI Agent Instructions
+
+Always read @SKILL.md for detailed metool knowledge.
diff --git a/AI.md b/AI.md
deleted file mode 100644
index 3fa4809..0000000
--- a/AI.md
+++ /dev/null
@@ -1,46 +0,0 @@
-# Metool AI Guide
-
-This guide helps AI agents understand and work effectively with metool.
-
-## What is Metool?
-
-Metool is the core configuration management tool that uses GNU Stow to manage symlinks. It operates on **metool modules** - separate git repositories that contain packages.
-
-## Core Concepts
-
-### Metool (the tool)
-- Core tool for managing configuration packages
-- Provides the `mt` command interface
-- Defines conventions and operations
-
-### Metool Modules
-- Separate git repositories containing packages
-- Examples: `metool-packages`, `metool-packages-dev`, `metool-packages-personal`
-- Cloned/managed via `mt sync`
-
-### Packages
-- Self-contained units within modules
-- Follow standard structure: `bin/`, `shell/`, `config/`, `lib/`, `libexec/`
-- Installed via `mt install <module>/<package>`
-
-## Essential Reading
-
-Always read these metool documentation files:
-- @docs/reference/commands/README.md - Complete command reference
-- @docs/conventions/package-structure.md - Package structure conventions
-- @docs/templates/service-package/README.md - Service package template (for service packages)
-
-## Key Points for AI Agents
-
-1. **Script Usage**: Use `mtbin` wrapper when calling from scripts (not `mt`). The `mtbin` command is available after metool is installed and can be used to run mt commands from scripts or other programs.
-2. **Package Structure**: Follow conventions in `docs/conventions/package-structure.md`
-3. **Service Packages**: For packages managing system services (systemd/launchd), use the template in `docs/templates/service-package/`. This provides unified command structure with install, start, stop, restart, status, enable, disable, logs, and config subcommands.
-4. **Naming**: Use lowercase-with-hyphens for packages
-5. **Documentation**: Every package needs a README.md
-
-## Quick Reference
-
-- `mt install <module>/<package>` - Install a package
-- `mt sync <module>` - Clone/update module repositories
-- `mt cd` - Navigate to metool directories
-- See full command list in docs/reference/commands/README.md
\ No newline at end of file
diff --git a/CLAUDE.md b/CLAUDE.md
index 098331f..5b8e39e 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -1,6 +1,3 @@
 # Claude Code Instructions
 
-Always read these files at the beginning of each session:
-- @AI.md
-
-<!-- Add any Claude-specific instructions below this line -->
+Load the metool skill: /metool
diff --git a/SKILL.md b/SKILL.md
index 8ca296d..9ae41e0 100644
--- a/SKILL.md
+++ b/SKILL.md
@@ -14,64 +14,60 @@ Metool (mt) is a modular system for managing shell environments through packages
 Use this skill when:
 - Creating new metool packages
 - Installing or modifying metool packages
-- Reviewing package structure and conventions
 - Working with metool commands (install, cd, edit, etc.)
 - Setting up configuration files or dotfiles via metool
-- Managing shell functions, aliases, or executables
 - Creating or updating Claude Code skills for metool packages
-- Adding SKILL.md to existing packages
 
-## Core Concepts
+## Quick Reference
 
 ### Package Structure
 
-Every metool package follows this standard structure:
-
 ```
 package-name/
-├── README.md        # Package documentation (REQUIRED)
-├── SKILL.md         # Claude Code skill (optional, enables AI assistance)
-├── bin/            # Executable scripts (symlinked to ~/.metool/bin)
-├── shell/          # Shell functions, aliases, completions
-├── config/         # Config files (use dot- prefix for dotfiles)
-├── lib/            # Library functions (sourced, not executed)
-├── libexec/        # Helper scripts (not in PATH)
-└── docs/           # Additional documentation
+├── README.md        # Required
+├── SKILL.md         # Optional (enables AI assistance)
+├── bin/             # Executables (symlinked to ~/.metool/bin)
+├── shell/           # Functions, aliases, completions
+├── config/          # Dotfiles (use dot- prefix)
+├── lib/             # Library functions
+├── libexec/         # Helper scripts (not in PATH)
+└── docs/            # Additional documentation
 ```
 
-### Installation Mechanism
+For complete conventions, see @docs/conventions/package-structure.md
+
+### Essential Commands
 
-Metool uses GNU Stow to create symlinks:
-- `bin/` → `~/.metool/bin/` (executables in PATH)
-- `shell/` → `~/.metool/shell/` (sourced on shell startup)
-- `config/` → `~/.metool/config/` → `~/` (dotfiles via --dotfiles)
+```bash
+mt package add module/package    # Add to working set
+mt package install package-name  # Install (create symlinks)
+mt cd package-name               # Navigate to package
+mt edit function-name            # Edit a function/script
+mt reload                        # Reload after changes
+```
 
-### Dotfile Naming Convention
+For all commands, see @docs/reference/commands/README.md
 
-Files in `config/` use `dot-` prefix which gets converted:
-- `config/dot-bashrc` → `~/.bashrc`
-- `config/dot-gitconfig` → `~/.gitconfig`
-- `config/dot-config/tool/` → `~/.config/tool/`
+### How mt Works
 
-This avoids hidden files in the repository while creating proper dotfiles in home directory.
+The `mt` command is a shell function (not a binary), which enables features like `mt cd` that change your current directory. Most functionality works through the function.
 
-## Creating a New Package
+**Fallback binary**: When the shell function isn't available (e.g., calling from scripts, cron, or non-bash shells), use `bin/mt` directly. This binary wrapper sources the function and executes commands, but some features like directory changing won't affect the parent shell.
 
-### Step 1: Create Package Directory Structure
+## Creating a Package
+
+### Step 1: Create Structure
 
 ```bash
-# Create package directory
 mkdir -p package-name/{bin,shell,config,lib}
 ```
 
-### Step 2: Create README.md
-
-Every package MUST have a README.md. Use this template:
+### Step 2: Create README.md (Required)
 
 ```markdown
 # Package Name
 
-Brief description of what this package provides
+Brief description
 
 ## Installation
 
@@ -82,101 +78,48 @@ mt package install package-name
 
 ## Components
 
-- `bin/tool-name` - Main tool for doing X
-- `shell/functions` - Helper functions for Y
-- `config/dot-toolrc` - Configuration file
+- `bin/tool-name` - Main tool
+- `shell/functions` - Helper functions
 
 ## Usage
 
 [Usage examples]
-
-## Requirements
-
-- bash 4.0+
-- other dependencies
 ```
 
-### Step 3: Add Package Components
+### Step 3: Add Components
 
-#### Executables (bin/)
+**Executables (bin/):**
 ```bash
-# Create executable script
 cat > package-name/bin/tool-name << 'EOF'
 #!/usr/bin/env bash
 # Tool description
 EOF
-
 chmod +x package-name/bin/tool-name
 ```
 
-Requirements for bin/ scripts:
-- Must be executable (`chmod +x`)
-- Should have shebang line
-- Names should be descriptive and unique
-
-#### Shell Functions (shell/)
-```bash
-# Create shell functions
-cat > package-name/shell/functions << 'EOF'
-# Function description
-function_name() {
-    # Implementation
-}
-EOF
-```
-
-Shell directory structure:
+**Shell Functions (shell/):**
 - `shell/functions` - Shell functions
 - `shell/aliases` - Command aliases
 - `shell/completions/` - Bash tab completion
-- `shell/environment` - Environment variable exports
+- `shell/environment` - Environment exports
 - `shell/path` - PATH modifications
 
-#### Configuration Files (config/)
-```bash
-# Create config with dot- prefix
-mkdir -p package-name/config
-cat > package-name/config/dot-toolrc << 'EOF'
-# Configuration
-EOF
-```
+**Dotfiles (config/):**
+Use `dot-` prefix: `config/dot-bashrc` → `~/.bashrc`
 
-Remember: Use `dot-` prefix for all dotfiles!
+See @docs/conventions/package-structure.md for full details.
 
-### Step 4: Install the Package
+### Step 4: Install
 
 ```bash
-mt install package-name
+mt package add module/package-name
+mt package install package-name
 ```
 
-This uses GNU Stow to create symlinks from package directories to `~/.metool/`.
-
-## Package Naming Conventions
-
-### Package Names
-- Lowercase with hyphens: `git-tools`, `docker-helpers`
-- Be descriptive but concise
-- Avoid generic names like `utils` or `misc`
-
-### Script Names
-- Lowercase with hyphens
-- Include package prefix if needed for clarity
-- Make purpose obvious
-
-Examples:
-- `git-branch-clean`
-- `docker-cleanup`
-- `aws-ec2-list`
-
-## Python Package Conventions
-
-When creating Python packages:
+## Python Scripts
 
-1. Use **uv** as the package manager
-2. Use inline script metadata (PEP 723) for dependencies
-3. Scripts in `bin/` should have no `.py` extension
+Use uv with PEP 723 inline script metadata:
 
-Example with inline dependencies:
 ```python
 #!/usr/bin/env python
 # /// script
@@ -186,491 +129,97 @@ Example with inline dependencies:
 
 import requests
 import click
-
 # Script implementation
 ```
 
-## Common Commands
-
-### mt package add
-Add a package from a module to your working set:
-```bash
-mt package add module/package    # Add package from module to working set
-mt package add dev/dependabot    # Example: add dependabot from dev module
-```
-
-### mt package install
-Install a package by symlinking its components:
-```bash
-mt package install package-name  # Install package (must be in working set)
-mt package install dependabot    # Example: install dependabot package
-```
-
-**Complete Installation Workflow:**
-```bash
-# Step 1: Add package to working set
-mt package add dev/dependabot
-
-# Step 2: Install package (create symlinks)
-mt package install dependabot
-```
-
-### mt install (deprecated)
-Legacy command for installing packages:
-```bash
-mt install package-name          # Install from current directory
-mt install path/to/package       # Install specific package
-```
-
-**Note:** Use `mt package add` + `mt package install` workflow instead.
-
-### mt cd
-Change to metool root or specific component:
-```bash
-mt cd                    # Go to metool root
-mt cd package-name       # Go to package directory
-```
-
-### mt edit
-Edit functions, executables, or files:
-```bash
-mt edit function-name    # Edit a shell function
-mt edit command-name     # Edit an executable
-```
-
-### mt components
-List all package components:
-```bash
-mt components            # List all components
-```
-
-### mt packages
-List all metool packages:
-```bash
-mt packages              # Show all packages with modules
-```
-
-### mt reload
-Reload metool configuration:
-```bash
-mt reload                # Reload shell configuration
-```
-
-## Discovering Packages and Modules
-
-### Listing Modules
-
-To see which modules are in the working set:
-
-```bash
-mt module list
-```
-
-Output shows module name and path:
-```
-    MODULE                         PATH
---- ------                         ----
-✓  dev                         /Users/admin/Code/github.com/mbailey/metool-packages-dev
-✓  pub                         /Users/admin/Code/github.com/mbailey/metool-packages
-```
-
-### Listing Packages
-
-To see which packages are in the working set:
-
-```bash
-mt package list
-```
-
-Output shows package name and full path where the symlink points:
-```
-    PACKAGE                        PATH
---- -------                        ----
-✓  git                        /Users/admin/Code/github.com/mbailey/metool-packages-dev/git
-✓  agents                     /Users/admin/Code/github.com/mbailey/agents
-```
-
-### Finding Specific Packages
-
-To conserve context when searching for a specific package, pipe through grep:
-
-```bash
-# Find packages matching 'git' (use word boundary to avoid matching 'github')
-mt package list | grep -w git
-
-# Find packages containing 'docker'
-mt package list | grep docker
-```
+Scripts in `bin/` should have no `.py` extension.
 
-**Context-efficient workflow:**
-1. Run `mt package list | grep <search-term>` to find the package
-2. Note the package name and path from the output
-3. Use the path directly instead of re-listing all packages
+## Service Packages
 
-This approach saves context by showing only relevant matches instead of loading all 200+ packages into the conversation.
+For packages managing systemd/launchd services, use the service package template.
 
-## Checking Dependencies
-
-Always check for required tools in scripts:
-
-```bash
-if ! command -v required-tool >/dev/null; then
-  echo "Error: required-tool is needed but not installed" >&2
-  exit 1
-fi
-```
-
-For metool package dependencies:
-```bash
-if ! command -v other-tool >/dev/null; then
-  echo "Error: other-tool from other-package is required" >&2
-  echo "Install with: mt package add module/other-package && mt package install other-package" >&2
-  exit 1
-fi
-```
-
-## Service Packages (systemd/launchd)
-
-For packages that install services, provide monitoring aliases in `shell/aliases`:
-
-```bash
-# macOS launchd example
-alias package-logs='tail -f ~/Library/Logs/package-service.log'
-alias package-status='launchctl list | grep package-service'
-alias package-start='launchctl load ~/Library/LaunchAgents/com.user.package.plist'
-alias package-stop='launchctl unload ~/Library/LaunchAgents/com.user.package.plist'
-
-# Linux systemd example
-alias package-logs='journalctl --user -u package-service -f'
-alias package-status='systemctl --user status package-service'
-alias package-start='systemctl --user start package-service'
-alias package-stop='systemctl --user stop package-service'
-alias package-restart='systemctl --user restart package-service'
-```
-
-## Module Organization
-
-Modules group related packages:
-
-```
-metool-packages/         # Public shared packages
-metool-packages-dev/     # Development packages
-metool-packages-personal/# Personal packages
-metool-packages-work/    # Work-specific packages
-```
-
-## Best Practices
-
-1. **One Purpose** - Each package should have a clear, focused purpose
-2. **Self-Contained** - Packages should work independently
-3. **Well-Documented** - Include README and inline documentation
-4. **Tested** - Test packages before installing
-5. **Dependencies** - Document and check for dependencies
+See @docs/templates/service-package/README.md for:
+- Cross-platform service management (Linux/macOS)
+- Standard subcommands: install, start, stop, restart, status, logs
+- Version detection and monitoring
+- Complete shell aliases pattern
 
 ## Claude Code Skills
 
-Skills extend Claude's capabilities by providing specialized knowledge, workflows, and tools. Metool packages can include a `SKILL.md` file to enable AI assistance for the package's domain.
-
-### What Skills Provide
-
-1. **Specialized workflows** - Multi-step procedures for specific domains
-2. **Tool integrations** - Instructions for working with specific file formats or APIs
-3. **Domain expertise** - Package-specific knowledge, schemas, conventions
-4. **Bundled resources** - Scripts, docs, and assets accessible to Claude
-
-### Human-AI Collaborative Infrastructure
-
-Metool packages with skills create infrastructure that serves both humans and AI:
-
-**For Humans:**
-- Scripts in `bin/` provide CLI tools available in PATH
-- Shell functions and aliases in `shell/` enhance interactive workflows
-- Configuration in `config/` manages dotfiles and settings
-- `README.md` documents the package for human users
-
-**For AI (Claude):**
-- `SKILL.md` provides procedural knowledge and workflow guidance
-- References to `bin/` scripts tell Claude what tools are available
-- Documentation in `docs/` enables progressive disclosure
-- Understanding of `shell/` functions helps Claude guide interactive usage
+Packages can include a `SKILL.md` file to enable AI assistance. This creates human-AI collaborative infrastructure where:
+- Humans get CLI tools, shell functions, and documentation
+- AI gets procedural knowledge, workflows, and tool references
 
 ### SKILL.md Structure
 
-Every skill requires a `SKILL.md` file with YAML frontmatter:
-
 ```markdown
 ---
 name: package-name
-description: Brief explanation of what the skill does and when to use it. This skill should be used when [specific scenarios].
+description: Brief explanation. This skill should be used when [scenarios].
 ---
 
 # Package Name
 
 ## Overview
-
-[1-2 sentences explaining what this skill enables]
-
-## When to Use
-
-[Specific triggers and use cases]
+[What this skill enables]
 
 ## Workflows
-
-[Step-by-step procedures, tool references, examples]
-
-## Resources
-
-[References to bin/ scripts, docs/ files, and other package components]
+[Step-by-step procedures with tool references]
 ```
 
-**Frontmatter Requirements:**
-- `name`: Must be hyphen-case (lowercase letters, digits, hyphens only)
-- `description`: Clear explanation of when Claude should use this skill. Use third-person ("This skill should be used when..." not "Use this skill when...")
-
-### Progressive Disclosure
-
-Skills use a three-level loading system:
-
-1. **Metadata** (~100 words) - Always in context (name + description)
-2. **SKILL.md body** (<5k words) - Loaded when skill triggers
-3. **Package resources** (unlimited) - Loaded as needed by Claude
-
-Scripts in `bin/` can be executed without loading into context, making them token-efficient.
-
-### Adding a Skill to an Existing Package
-
-When adding a skill to an existing metool package:
-
-1. **Create only the SKILL.md file** - Do not overwrite existing README.md or other files
-2. **Reference existing tools** - Review what scripts, functions, and docs already exist
-3. **Adapt to existing structure** - The SKILL.md should work with the package's current organization
-
-Example: Adding a skill to a `git-tools` package that already has `bin/git-branch-clean`:
+### Key Points
 
-```markdown
----
-name: git-tools
-description: Git workflow utilities for branch management and repository maintenance. This skill should be used when cleaning up git branches, managing worktrees, or automating git workflows.
----
-
-# Git Tools
-
-## Overview
-
-Provides utilities for git branch management and repository maintenance.
+- Use third-person in description ("This skill should be used when...")
+- Keep under 5k words; move details to docs/
+- Reference package tools by command name (they're in PATH after install)
+- Focus on procedural knowledge Claude cannot infer
 
-## Available Tools
+See @docs/conventions/package-structure.md#skillmd-optional for frontmatter requirements and installation mechanism.
 
-- `git-branch-clean` - Remove merged local branches
-- `git-worktree-list` - List all worktrees with status
-
-## Workflows
-
-### Cleaning Up Branches
-
-To clean up merged branches, run:
-\`\`\`bash
-git-branch-clean
-\`\`\`
-```
-
-### Creating a New Package with Skill
-
-To create a new metool package with skill support:
+### Creating a Package with Skill
 
 ```bash
 mt package new my-package /path/to/module
 ```
 
-This creates a package from the template including `SKILL.md.example`:
-```
-my-package/
-├── README.md           # Human documentation template
-├── SKILL.md.example    # Claude skill template (rename to SKILL.md to activate)
-├── bin/                # Executable scripts directory
-├── shell/              # Shell functions directory
-├── config/             # Configuration files
-└── lib/                # Library functions directory
-```
-
-To enable the skill, rename `SKILL.md.example` to `SKILL.md` and complete the TODOs.
+Creates package from template including `SKILL.md.example`. Rename to `SKILL.md` to activate.
 
-### Skill Commands
-
-Metool provides commands for skill management:
+## Discovering Packages
 
 ```bash
-# Create a new package (includes SKILL.md.example template)
-mt package new <package-name> [directory]
-
-# Validate package structure and SKILL.md
-mt package validate <package-name|path>
+mt module list                    # List modules
+mt package list                   # List all packages
+mt package list | grep -w git     # Find specific package
 ```
 
-### Documentation Strategy
-
-- **README.md** - Human-facing: installation, usage examples, requirements
-- **SKILL.md** - AI-facing: procedural knowledge, workflows, tool references
-- **docs/** - Shared reference: detailed schemas, APIs, conventions
-
-Avoid duplication between README.md and SKILL.md. Each should serve its audience.
-
-### Writing Effective Skills
-
-**Writing Style:** Use imperative/infinitive form (verb-first instructions), not second person. Write "To accomplish X, do Y" rather than "You should do X".
+**Context-efficient workflow**: Use grep to filter rather than loading full list.
 
-**Content Guidelines:**
-- Focus on procedural knowledge that Claude cannot infer
-- Reference package tools by their command names (they're in PATH after install)
-- Point to docs/ files for detailed reference material
-- Include concrete examples with realistic scenarios
-- Keep SKILL.md under 5k words; move details to docs/
-
-### Skill Installation
-
-When a package with `SKILL.md` is installed via `mt package install`, metool automatically creates symlinks to make the skill available to Claude Code:
-
-1. Package directory → `~/.metool/skills/<package-name>`
-2. `~/.metool/skills/<package-name>` → `~/.claude/skills/<package-name>`
+## Checking Dependencies
 
-Claude Code discovers skills by scanning `~/.claude/skills/` for `SKILL.md` files.
+```bash
+if ! command -v required-tool >/dev/null; then
+  echo "Error: required-tool is needed but not installed" >&2
+  exit 1
+fi
+```
 
 ## Troubleshooting
 
 ### Conflicts During Installation
-
-When installing config files that already exist:
-1. The command shows which files conflict
-2. You're prompted to remove existing files
-3. If accepted, conflicting file is removed and installation retries
-4. Broken symlinks are identified and can be safely removed
+When config files conflict, the command prompts to remove existing files and retry.
 
 ### Prerequisites
-
-Metool requires:
-- **GNU coreutils** (for `realpath`)
-  - macOS: `brew install coreutils`
-  - Ubuntu: Usually pre-installed
-- **GNU Stow 2.4.0+** (for `mt install`)
-  - macOS: `brew install stow`
-  - Ubuntu: `apt install stow`
-
-Check dependencies:
 ```bash
 mt deps              # Check dependencies
-mt deps --install    # Auto-install on macOS
+mt deps --install    # Auto-install on macOS (requires Homebrew)
 ```
 
-## Documentation Resources
-
-For detailed information, refer to existing metool documentation:
-
-### Core Documentation
-- `README.md` - Main metool documentation and quickstart
-- `docs/conventions/package-structure.md` - Complete package structure conventions
-- `docs/reference/commands/` - Individual command documentation
-
-### Guides
-- `docs/guides/repository-management.md` - Managing repositories with metool
-- `docs/systemd.md` - Systemd service management
-
-### Conventions
-- `docs/conventions/shell-scripting.md` - Shell scripting best practices
-- `docs/conventions/documentation.md` - Documentation standards
-- `docs/conventions/testing.md` - Testing guidelines
-
-### Templates
-- `docs/templates/service-package/` - Service package template
-
-Use the Read tool to load specific documentation files as needed during package development
-
-## Example: Creating a Service Package
-
-Here's a complete example of creating a CopyParty file sharing package:
-
-```bash
-# 1. Create structure
-mkdir -p copyparty/{bin,config/dot-config/copyparty,lib/launchd}
-
-# 2. Create README
-cat > copyparty/README.md << 'EOF'
-# CopyParty File Sharing
+Requires: GNU coreutils, GNU Stow 2.4.0+
 
-File sharing service via CopyParty
-
-## Installation
-\`\`\`bash
-mt install copyparty
-\`\`\`
-
-## Components
-- `bin/copyparty-install` - Installation script
-- `config/.config/copyparty/config.yaml` - Configuration
-- `lib/launchd/com.user.copyparty.plist` - Launch agent
-
-## Usage
-Service starts automatically on login
-EOF
-
-# 3. Create installation script
-cat > copyparty/bin/copyparty-install << 'EOF'
-#!/usr/bin/env bash
-set -euo pipefail
-
-# Install copyparty via uv
-uv tool install copyparty
-
-# Install launchd service
-cp lib/launchd/com.user.copyparty.plist ~/Library/LaunchAgents/
-launchctl load ~/Library/LaunchAgents/com.user.copyparty.plist
-EOF
-
-chmod +x copyparty/bin/copyparty-install
-
-# 4. Create configuration
-cat > copyparty/config/dot-config/copyparty/config.yaml << 'EOF'
-port: 3923
-directories:
-  - path: ~/.cora
-    permissions: read,write
-EOF
-
-# 5. Create launchd plist
-cat > copyparty/lib/launchd/com.user.copyparty.plist << 'EOF'
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
-<plist version="1.0">
-<dict>
-    <key>Label</key>
-    <string>com.user.copyparty</string>
-    <key>ProgramArguments</key>
-    <array>
-        <string>/usr/local/bin/uvx</string>
-        <string>copyparty</string>
-        <string>--http-only</string>
-        <string>-p</string>
-        <string>3923</string>
-        <string>/Users/admin/.cora</string>
-        <string>--read</string>
-        <string>--write</string>
-    </array>
-    <key>RunAtLoad</key>
-    <true/>
-    <key>KeepAlive</key>
-    <true/>
-</dict>
-</plist>
-EOF
-
-# 6. Add package to working set (if in a module)
-# Assuming copyparty is in a module, e.g., services module
-mt package add services/copyparty
-
-# 7. Install the package
-mt package install copyparty
-
-# 8. Run installation script
-copyparty-install
-```
+## Documentation Resources
 
-This example demonstrates all key concepts: structure, dotfile naming, service management, and installation workflow.
+- @docs/conventions/package-structure.md - Complete package conventions
+- @docs/conventions/shell-scripting.md - Shell scripting best practices
+- @docs/reference/commands/README.md - Command reference
+- @docs/templates/service-package/README.md - Service package template
+- @docs/guides/GETTING-STARTED.md - Getting started guide
diff --git a/docs/conventions/README.md b/docs/conventions/README.md
index 0153b12..5497f82 100644
--- a/docs/conventions/README.md
+++ b/docs/conventions/README.md
@@ -1,18 +1,18 @@
 # Metool Conventions
 
-This directory contains coding conventions and best practices for metool development.
+Coding conventions and best practices for development of metool itself, as well as metool modules and packages.
 
 ## Overview
 
-These conventions ensure consistency across the metool codebase and make it easier for contributors to understand and extend the project.
+These conventions ensure consistency across metool and metool packages, making it easier for contributors and AI agents to understand and extend the project.
 
 ## Conventions
 
 - [Shell Scripting](shell-scripting.md) - Bash coding standards and patterns
 - [Testing](testing.md) - How to write and organize tests
-- [Documentation](documentation.md) - Documentation standards and structure
-- [Documentation Organization](documentation-organization.md) - How to organize documentation files
+- [Documentation](documentation/README.md) - Documentation standards and structure
 - [Package Structure](package-structure.md) - How to structure metool packages
+- [Symlinks](symlinks.md) - Symlink handling conventions
 
 ## General Principles
 
@@ -29,4 +29,4 @@ When adding new features or modifying existing ones:
 1. Follow the conventions outlined in these documents
 2. Update tests to cover your changes
 3. Update documentation as needed
-4. Ensure all tests pass before submitting
\ No newline at end of file
+4. Ensure all tests pass before submitting
diff --git a/docs/conventions/documentation-organization.md b/docs/conventions/documentation-organization.md
deleted file mode 100644
index 178b084..0000000
--- a/docs/conventions/documentation-organization.md
+++ /dev/null
@@ -1,82 +0,0 @@
-# Documentation Organization
-
-Guidelines for organizing and maintaining documentation files in the project.
-
-## File Naming Conventions
-
-- Use lowercase with hyphens: `error-handling.md`, not `ErrorHandling.md`
-- Be specific: `function-naming.md` rather than `naming.md`
-- Group related topics: `testing-patterns.md`, `testing-bats.md`
-
-## Content Guidelines
-
-### When to Create New Files
-
-Split content into separate files when:
-- A section exceeds ~50 lines
-- The topic is self-contained
-- Multiple subtopics exist (create a directory)
-- Different audiences need different content
-
-### Link Conventions
-
-```markdown
-# Good - descriptive link text
-See [Function Naming Patterns](./function-naming.md) for details.
-
-# Bad - vague link text
-See [here](./function-naming.md) for more.
-```
-
-### File Headers
-
-Each file should start with:
-```markdown
-# Clear Title
-
-Brief description of what this document covers.
-
-## When to Read This
-- Specific scenarios when this is relevant
-```
-
-## Maintenance
-
-### Adding Content
-1. Check if it fits in existing files first
-2. Create new files only for distinct topics
-3. Update parent README.md with links
-4. Keep files focused on single topics
-
-### Removing Content
-1. Check for incoming links before deleting
-2. Redirect or update linking documents
-3. Consider archiving vs deleting
-
-## Examples
-
-### Good Structure
-```
-conventions/
-├── README.md           # Overview and common patterns
-├── testing/           # Testing-related conventions
-│   ├── README.md      # Testing overview
-│   ├── bats.md        # BATS-specific patterns
-│   └── examples/      # Example test files
-└── naming.md          # Naming conventions
-```
-
-### Poor Structure
-```
-conventions/
-├── everything.md      # 500+ line file
-├── misc.md           # Grab bag of unrelated items
-└── temp.md           # Unclear purpose
-```
-
-## Key Principles
-
-1. **Discoverable** - Clear names and organization
-2. **Focused** - One topic per file
-3. **Linked** - Connected documentation
-4. **Maintainable** - Easy to update and extend
\ No newline at end of file
diff --git a/docs/conventions/documentation.md b/docs/conventions/documentation.md
deleted file mode 100644
index be8d261..0000000
--- a/docs/conventions/documentation.md
+++ /dev/null
@@ -1,249 +0,0 @@
-# Documentation Conventions
-
-## File Structure
-
-```
-docs/
-├── README.md                 # Main documentation entry point
-├── conventions/             # Coding standards and practices
-│   ├── README.md
-│   ├── shell-scripting.md
-│   ├── testing.md
-│   └── documentation.md
-├── reference/              # Command reference
-│   └── commands/
-│       ├── README.md
-│       ├── cd.md
-│       ├── edit.md
-│       └── ...
-└── guides/                 # How-to guides
-    └── ...
-```
-
-## Markdown Standards
-
-### Headers
-Use ATX-style headers with proper hierarchy:
-
-```markdown
-# Main Title
-
-## Section
-
-### Subsection
-
-#### Sub-subsection
-```
-
-### Code Blocks
-Always specify the language for syntax highlighting:
-
-````markdown
-```bash
-mt edit ~/.bashrc
-```
-
-```python
-def example():
-    pass
-```
-````
-
-### Lists
-Use consistent list markers:
-
-```markdown
-- First item
-- Second item
-  - Nested item
-  - Another nested item
-- Third item
-
-1. Numbered item
-2. Another numbered item
-   - Can mix bullets in numbered lists
-3. Final numbered item
-```
-
-## Command Documentation
-
-Each command should have its own file in `docs/reference/commands/` with this structure:
-
-```markdown
-# mt <command>
-
-Brief description of what the command does
-
-## Usage
-
-```bash
-mt <command> [options] <arguments>
-```
-
-## Description
-
-Detailed explanation of the command's purpose and behavior
-
-## Options
-
-- `-h, --help` - Show help message
-- `-v, --verbose` - Enable verbose output
-
-## Arguments
-
-- `<argument>` - Description of the argument
-
-## Examples
-
-```bash
-# Example 1 with description
-mt command arg1
-
-# Example 2 with description  
-mt command --option arg2
-```
-
-## Environment Variables
-
-- `MT_ROOT` - Description of how it affects the command
-- `EDITOR` - Used for editing files
-
-## Notes
-
-Additional information, caveats, or tips
-
-## See Also
-
-- [mt other-command](other-command.md) - Related command
-```
-
-## Code Comments
-
-### Function Documentation
-Document functions at the definition:
-
-```bash
-# Get all metool modules with caching
-# Returns: TSV list of module_name<tab>module_path
-# Example: public<tab>/home/user/.metool-public
-_mt_get_modules() {
-  # Implementation
-}
-```
-
-### Inline Comments
-Explain complex logic:
-
-```bash
-# Use read to properly handle spaces in paths
-read -r _ _ source_file <<< "$func_output"
-
-# Check if array has elements (not if it's defined)
-if ((${#funcinfo[@]} > 0)); then
-```
-
-## Examples
-
-### Good Examples
-- Show common use cases first
-- Include output when helpful
-- Explain what the example does
-
-```markdown
-```bash
-# Change to the directory containing a function
-mt cd _mt_sync
-# Changes to: /home/user/metool/lib
-
-# Edit a configuration file
-mt edit ~/.bashrc
-# Opens: ~/.bashrc in your $EDITOR
-```
-```
-
-### Bad Examples
-- Don't use foo/bar unless necessary
-- Avoid overly complex examples
-- Don't assume specific paths
-
-## Writing Style
-
-### Be Concise
-- Use short, clear sentences
-- Avoid unnecessary words
-- Get to the point quickly
-
-### Be Consistent
-- Use the same terminology throughout
-- Follow the same structure for similar content
-- Maintain the same tone
-
-### Use Active Voice
-- "The command creates a file" ✓
-- "A file is created by the command" ✗
-
-### Present Tense
-- "Returns the path" ✓
-- "Will return the path" ✗
-- "Returned the path" ✗
-
-## Updating Documentation
-
-When making changes:
-
-1. **Update affected documentation** - If you change behavior, update docs
-2. **Add examples** - Show new features with examples
-3. **Update cross-references** - Ensure links still work
-4. **Check for accuracy** - Test examples to ensure they work
-
-## API Documentation
-
-For functions meant to be used by others:
-
-```bash
-# Public: Get the absolute path to a metool module
-#
-# $1 - Module name
-#
-# Examples:
-#
-#   module_path=$(mt_get_module_path "public")
-#   echo "$module_path"  # /home/user/.metool-public
-#
-# Returns: 
-#   0 - Success, prints module path to stdout
-#   1 - Module not found
-mt_get_module_path() {
-  # Implementation
-}
-```
-
-## Special Sections
-
-### Warnings
-Use blockquotes for warnings:
-
-```markdown
-> **Warning**: This command modifies files in place. Make backups first.
-```
-
-### Notes
-Use blockquotes for important notes:
-
-```markdown
-> **Note**: This feature requires bash 4.0 or later.
-```
-
-### Tips
-Use details for optional tips:
-
-```markdown
-<details>
-<summary>💡 Tip: Speed up searches</summary>
-
-Use more specific patterns to reduce search time:
-- `mt edit _mt_` finds functions starting with _mt_
-- `mt edit config` might match many files
-
-</details>
-```
\ No newline at end of file
diff --git a/docs/conventions/documentation/README.md b/docs/conventions/documentation/README.md
new file mode 100644
index 0000000..757a863
--- /dev/null
+++ b/docs/conventions/documentation/README.md
@@ -0,0 +1,132 @@
+# Documentation Conventions
+
+Standards for documentation in metool and metool packages.
+
+## Documentation Types
+
+| Type | Location | Purpose |
+|------|----------|---------|
+| [Project README](#project-readme) | `/README.md` | Entry point, installation, overview |
+| [Directory README](#directory-readme) | `*/README.md` | Folder contents and navigation |
+| [Root files](#root-files) | Project root | AGENTS.md, SKILL.md, CHANGELOG.md, etc. |
+| [Docs folder](#docs-folder) | `/docs/` | Detailed guides and references |
+| [Command help](#command-help) | CLI `--help` | Usage, options, examples |
+| [Code comments](#code-comments) | Source files | Function docs, inline notes |
+
+## Project README
+
+Root-level README.md serving as the main entry point:
+
+```markdown
+# Project Name
+
+Brief description (1-2 sentences)
+
+## Installation
+
+Quick install steps
+
+## Usage
+
+Common examples
+
+## Documentation
+
+Link to docs/ for more
+```
+
+See [readme-guide.md](readme-guide.md) for full templates.
+
+## Directory README
+
+README.md files in subdirectories for progressive disclosure:
+
+- List what the directory contains
+- Link to files within the directory
+- Provide brief context for each item
+- Keep under 50 lines when possible
+
+See [readme-guide.md](readme-guide.md) for the pattern.
+
+## Root Files
+
+Documentation files that live outside `docs/`:
+
+- **AGENTS.md** - AI agent instructions (industry standard)
+- **SKILL.md** - Claude Code skill definition
+- **CONTRIBUTING.md** - Contribution guidelines
+- **CHANGELOG.md** - Version history
+
+See [root-documentation.md](root-documentation.md) for the complete list.
+
+## Docs Folder
+
+**For metool packages**: Use a flat docs/ directory with topic-based files. Add suffixes (`-guide`, `-reference`, `-concepts`) only when disambiguation helps.
+
+```
+docs/
+├── README.md           # Optional overview
+├── installation.md     # Single-topic file
+├── advanced-guide.md   # How-to with suffix
+└── commands/           # Command reference (matches bin/)
+    ├── tool-name.md    # Matches bin/tool-name
+    └── other-cmd.md
+```
+
+For command reference, create a `docs/commands/` directory with one file per command, named identically to the binary in `bin/`. This makes it easy to find documentation for any command.
+
+**For metool core and large projects**: Use category-based subdirectories when documentation grows beyond 10-15 files:
+
+```
+docs/
+├── reference/      # API docs, command reference
+├── guides/         # How-to tutorials
+├── templates/      # Reusable templates
+└── development/    # Contributor docs
+```
+
+See [docs-structure.md](docs-structure.md) for details and [docs-structure-concepts.md](docs-structure-concepts.md) for background on when to use each approach.
+
+## Command Help
+
+CLI commands should provide `--help` output with:
+- Usage syntax
+- Option descriptions
+- Common examples
+
+Reference documentation lives in `docs/reference/commands/`.
+
+See [command-usage.md](command-usage.md) for the template.
+
+## Code Comments
+
+Function and inline documentation:
+
+```bash
+# Brief description of function
+# $1 - First argument
+# Returns: Description of output
+function_name() {
+    # Explain complex logic inline
+}
+```
+
+See [writing-style.md](writing-style.md) for conventions.
+
+## Quick Reference
+
+- **File naming**: lowercase-with-hyphens.md
+- **File suffixes**: `-guide`, `-reference`, `-concepts`
+- **Headers**: ATX-style (`#`, `##`, `###`)
+- **Code blocks**: Always specify language
+- **Voice**: Active, present tense
+- **Length**: Keep files focused; split at ~50 lines
+
+## Detailed Guides
+
+- [readme-guide.md](readme-guide.md) - Project and directory README templates
+- [root-documentation.md](root-documentation.md) - Files outside docs/
+- [docs-structure.md](docs-structure.md) - Standard docs folder layout
+- [docs-structure-concepts.md](docs-structure-concepts.md) - Diátaxis vs topic-based
+- [command-usage.md](command-usage.md) - CLI documentation conventions
+- [writing-style.md](writing-style.md) - Markdown, tone, formatting
diff --git a/docs/conventions/documentation/command-usage.md b/docs/conventions/documentation/command-usage.md
new file mode 100644
index 0000000..07716a0
--- /dev/null
+++ b/docs/conventions/documentation/command-usage.md
@@ -0,0 +1,258 @@
+# Command Documentation
+
+Standards for CLI command help text and reference documentation.
+
+## Two Locations
+
+Command documentation exists in two places:
+
+1. **CLI `--help`** - Built into the command, shown at runtime
+2. **docs/reference/commands/** - Markdown files for detailed reference
+
+Both should be consistent but serve different purposes.
+
+## CLI Help Text
+
+The `--help` output users see when running a command.
+
+### Template
+
+```
+command-name - Brief one-line description
+
+USAGE:
+    command-name [OPTIONS] <ARGUMENTS>
+
+ARGUMENTS:
+    <arg>           Description of required argument
+    [optional]      Description of optional argument
+
+OPTIONS:
+    -h, --help      Show this help
+    -v, --verbose   Enable verbose output
+    -q, --quiet     Suppress non-error output
+
+EXAMPLES:
+    command-name file.txt
+        Process a single file
+
+    command-name -v *.txt
+        Process all text files with verbose output
+
+ENVIRONMENT:
+    VARIABLE_NAME   Description of how it affects behavior
+```
+
+### Guidelines
+
+- First line: `command - description` (lowercase, no period)
+- Usage: Show actual syntax with brackets for optional
+- Arguments: Required in `<angle>`, optional in `[brackets]`
+- Options: Short form, long form, description
+- Examples: Show common cases with brief explanations
+- Keep under 40 lines when possible
+
+### Bash Implementation
+
+```bash
+show_help() {
+    cat << 'EOF'
+mt-example - Brief description of command
+
+USAGE:
+    mt-example [OPTIONS] <file>
+
+OPTIONS:
+    -h, --help      Show this help
+    -v, --verbose   Enable verbose output
+
+EXAMPLES:
+    mt-example config.yml
+        Process the config file
+EOF
+}
+
+# In main():
+case "$1" in
+    -h|--help) show_help; exit 0 ;;
+esac
+```
+
+## Reference Documentation
+
+Markdown files in `docs/reference/commands/` for detailed reference.
+
+### Template
+
+```markdown
+# mt command
+
+Brief description of what the command does.
+
+## Usage
+
+\`\`\`bash
+mt command [OPTIONS] <arguments>
+\`\`\`
+
+## Description
+
+Detailed explanation of the command's purpose, behavior, and when to use it.
+
+## Options
+
+| Option | Description |
+|--------|-------------|
+| `-h, --help` | Show help message |
+| `-v, --verbose` | Enable verbose output |
+| `--option VALUE` | Description with value |
+
+## Arguments
+
+| Argument | Required | Description |
+|----------|----------|-------------|
+| `<file>` | Yes | The file to process |
+| `[output]` | No | Optional output path |
+
+## Examples
+
+### Basic Usage
+
+\`\`\`bash
+mt command file.txt
+\`\`\`
+
+Description of what this does.
+
+### With Options
+
+\`\`\`bash
+mt command --verbose file.txt
+# Output: Processing file.txt...
+\`\`\`
+
+### Common Workflow
+
+\`\`\`bash
+# First, do this
+mt command --setup
+
+# Then do this
+mt command file.txt
+\`\`\`
+
+## Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `MT_ROOT` | `~/.metool` | Root directory |
+| `EDITOR` | `vi` | Editor for --edit |
+
+## Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| 0 | Success |
+| 1 | General error |
+| 2 | Invalid arguments |
+
+## Notes
+
+- Important caveats or tips
+- Platform-specific behavior
+- Performance considerations
+
+## See Also
+
+- [mt related-command](related-command.md) - Description
+- [Guide: Common Workflow](../../guides/workflow.md)
+```
+
+### Directory Structure
+
+```
+docs/reference/commands/
+├── README.md       # Index of all commands
+├── cd.md
+├── edit.md
+├── install.md
+└── ...
+```
+
+### README.md for Commands
+
+```markdown
+# Command Reference
+
+All mt commands with brief descriptions.
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| [cd](cd.md) | Change to metool directories |
+| [edit](edit.md) | Edit functions and files |
+| [install](install.md) | Install packages |
+
+## Categories
+
+### Package Management
+- [install](install.md) - Install packages
+- [packages](packages.md) - List packages
+
+### Navigation
+- [cd](cd.md) - Change directory
+- [edit](edit.md) - Edit files
+```
+
+## Consistency Between Help and Docs
+
+- Same option names and descriptions
+- Same examples (docs can have more)
+- Update both when commands change
+- Docs can expand on help text but shouldn't contradict
+
+## Subcommands
+
+For commands with subcommands like `mt git`:
+
+### Help Text
+
+```
+mt git - Git repository management
+
+USAGE:
+    mt git <COMMAND>
+
+COMMANDS:
+    add         Add repository to manifest
+    pull        Pull all repositories
+    push        Push all repositories
+    repos       List repositories
+
+Run 'mt git <command> --help' for command-specific help.
+```
+
+### Reference Docs
+
+Create a parent file `git.md` that links to subcommand docs:
+
+```markdown
+# mt git
+
+Git repository management commands.
+
+## Subcommands
+
+| Command | Description |
+|---------|-------------|
+| [add](git-add.md) | Add repository to manifest |
+| [pull](git-pull.md) | Pull all repositories |
+
+## Common Usage
+
+\`\`\`bash
+mt git pull    # Update all repos
+mt git push    # Push all changes
+\`\`\`
+```
diff --git a/docs/conventions/documentation/docs-structure-concepts.md b/docs/conventions/documentation/docs-structure-concepts.md
new file mode 100644
index 0000000..2ffcaa8
--- /dev/null
+++ b/docs/conventions/documentation/docs-structure-concepts.md
@@ -0,0 +1,133 @@
+# Documentation Structure Concepts
+
+Background on documentation organization approaches and when to use each.
+
+## Two Main Approaches
+
+### Category-Based (Diátaxis)
+
+Organize by documentation type:
+
+```
+docs/
+├── tutorials/    # Learning-oriented
+├── guides/       # Task-oriented
+├── reference/    # Information-oriented
+└── explanation/  # Understanding-oriented
+```
+
+The [Diátaxis framework](https://diataxis.fr/) by Daniele Procida identifies four types of documentation, each serving a different user need:
+
+| Type | Purpose | User Question |
+|------|---------|---------------|
+| Tutorials | Learn by doing | "Teach me" |
+| How-to Guides | Accomplish a task | "How do I...?" |
+| Reference | Look up details | "What is...?" |
+| Explanation | Understand concepts | "Why...?" |
+
+**Advantages:**
+- Clear purpose for each section
+- Readers know where to look
+- Scales well for large doc sets
+- Encourages complete coverage
+
+**Challenges:**
+- Overhead for small projects
+- Can separate related content
+- Requires discipline to maintain
+
+### Topic-Based
+
+Organize by subject, using suffixes to indicate type:
+
+```
+docs/
+├── authentication.md           # Overview
+├── authentication-guide.md     # How to set up
+├── authentication-reference.md # API details
+└── database.md                 # Different topic
+```
+
+**Advantages:**
+- Related content stays together
+- Simpler for small doc sets
+- Easier to navigate by topic
+- Natural for package documentation
+
+**Challenges:**
+- Less clear structure
+- Can become disorganized at scale
+- Type boundaries less obvious
+
+## When to Use Each
+
+### Use Category-Based When:
+
+- Documentation exceeds 20+ pages
+- Multiple distinct audiences (users vs developers)
+- Comprehensive reference documentation exists
+- Dedicated documentation team maintains it
+- Project has tutorials, guides, AND reference
+
+### Use Topic-Based When:
+
+- Documentation is small to medium
+- Single primary audience
+- Each topic is self-contained
+- Developers write docs alongside code
+- Package or library documentation
+
+## Hybrid Approach
+
+Metool uses a hybrid:
+
+- **Metool core**: Category-based with `reference/`, `guides/`, `conventions/`
+- **Metool packages**: Topic-based with `-guide`, `-reference` suffixes
+
+This balances structure for the core project with simplicity for packages.
+
+## The Four Documentation Types
+
+Understanding these types helps regardless of which structure you use:
+
+### 1. Tutorials (Learning)
+
+- Walk through from start to finish
+- "Follow along and do this"
+- Designed for beginners
+- Example: "Getting Started with Metool"
+
+### 2. How-to Guides (Tasks)
+
+- Steps to accomplish specific goals
+- "How do I configure X?"
+- Assumes some knowledge
+- Example: "How to Create a Service Package"
+
+### 3. Reference (Information)
+
+- Technical descriptions
+- Complete, accurate, concise
+- For looking things up
+- Example: Command reference, API docs
+
+### 4. Explanation (Understanding)
+
+- Background and context
+- "Why does this work this way?"
+- Discusses alternatives and tradeoffs
+- Example: This document
+
+## Practical Tips
+
+1. **Start simple** - Begin with topic-based, add structure as needed
+2. **Don't force it** - Not every doc fits neatly into one type
+3. **Cross-link** - Connect related content regardless of structure
+4. **README as hub** - Use README.md files to navigate any structure
+5. **Evolve gradually** - Reorganize when pain points emerge
+
+## Further Reading
+
+- [Diátaxis](https://diataxis.fr/) - The original framework
+- [Write the Docs](https://www.writethedocs.org/) - Documentation community
+- [Google Developer Documentation Style Guide](https://developers.google.com/style)
diff --git a/docs/conventions/documentation/docs-structure.md b/docs/conventions/documentation/docs-structure.md
new file mode 100644
index 0000000..be77039
--- /dev/null
+++ b/docs/conventions/documentation/docs-structure.md
@@ -0,0 +1,142 @@
+# Docs Folder Structure
+
+Standard layout for the `/docs/` directory in metool and metool packages.
+
+## Two Approaches
+
+There are two valid ways to organize documentation:
+
+1. **Category-based** (Diátaxis) - Separate directories for reference, guides, etc.
+2. **Topic-based** - Files grouped by topic with suffixes like `-guide`, `-reference`
+
+See [docs-structure-concepts.md](docs-structure-concepts.md) for when to use each.
+
+**For metool itself**: Use category-based (the full structure below).
+
+**For metool packages**: Use topic-based (simpler, see below).
+
+## Full Structure (Category-Based)
+
+For larger projects like metool core:
+
+```
+docs/
+├── README.md           # Entry point
+├── conventions/        # Standards and best practices
+│   ├── README.md
+│   └── *.md
+├── reference/          # Command reference, API docs
+│   ├── README.md
+│   └── commands/
+├── guides/             # How-to tutorials
+│   ├── README.md
+│   └── *.md
+├── templates/          # Reusable templates
+│   └── */
+└── development/        # Contributor docs
+    ├── README.md
+    └── *.md
+```
+
+### Directory Purposes
+
+| Directory | Content | Audience |
+|-----------|---------|----------|
+| conventions/ | Rules, patterns, standards | Contributors |
+| reference/ | Commands, API, config options | All users |
+| guides/ | Step-by-step tutorials | Users learning |
+| templates/ | Copy-and-modify starting points | Package authors |
+| development/ | Architecture, releases, internals | Maintainers |
+
+## Simple Structure (Topic-Based)
+
+For metool packages and smaller projects:
+
+```
+docs/
+├── README.md              # Overview and navigation
+├── topic-guide.md         # How to do X
+├── topic-reference.md     # Details about X
+└── another-topic.md       # Single file if small
+```
+
+### File Suffixes
+
+Use suffixes to indicate document type:
+
+| Suffix | Purpose | Example |
+|--------|---------|---------|
+| `-guide` | How to accomplish a goal | `authentication-guide.md` |
+| `-reference` | Technical details, options | `cli-reference.md` |
+| `-concepts` | Background, theory, "why" | `architecture-concepts.md` |
+
+No suffix needed for:
+- README.md files
+- Single-topic files that are self-explanatory
+- Files where the type is obvious from context
+
+## File Naming
+
+- Lowercase with hyphens: `getting-started.md`
+- Be specific: `shell-scripting.md` not `scripting.md`
+- Avoid abbreviations: `configuration.md` not `config.md`
+- Group related: `testing-patterns.md`, `testing-bats.md`
+
+## When to Create Subdirectories
+
+Create a subdirectory when:
+- 4+ related files exist
+- Logical grouping is clear
+- Different audiences need different content
+
+Examples:
+- `reference/commands/` - Many command docs
+- `conventions/documentation/` - Multiple doc standards
+
+## README.md in docs/
+
+The top-level docs/README.md should:
+
+1. List all major sections with links
+2. Provide a reading order for newcomers
+3. Describe what each section contains
+
+Example:
+
+```markdown
+# Documentation
+
+## For Users
+
+- [Getting Started](guides/getting-started.md)
+- [Command Reference](reference/commands/)
+
+## For Contributors
+
+- [Development Setup](development/setup.md)
+- [Conventions](conventions/)
+```
+
+## Cross-Linking
+
+Use relative links between docs:
+- `[Shell Scripting](../conventions/shell-scripting.md)`
+- `[mt cd command](../reference/commands/cd.md)`
+
+Avoid:
+- Absolute paths
+- Bare URLs to other files
+- "Click here" link text
+
+## Maintenance
+
+When adding content:
+1. Check if it fits in existing files
+2. Create new files only for distinct topics
+3. Update parent README.md with links
+4. Keep files focused on single topics
+
+When removing content:
+1. Check for incoming links
+2. Update or redirect linking documents
+3. Update parent README.md
diff --git a/docs/conventions/documentation/readme-guide.md b/docs/conventions/documentation/readme-guide.md
new file mode 100644
index 0000000..91b96f4
--- /dev/null
+++ b/docs/conventions/documentation/readme-guide.md
@@ -0,0 +1,228 @@
+# README Guide
+
+Templates and conventions for project and directory README files.
+
+## Project README
+
+The root-level README.md serves as the main entry point for humans and AI agents.
+
+### Template
+
+```markdown
+# Project Name
+
+Brief description of what this project does (1-2 sentences).
+
+## Installation
+
+\`\`\`bash
+# Installation command
+\`\`\`
+
+## Quick Start
+
+\`\`\`bash
+# Most common usage example
+\`\`\`
+
+## Features
+
+- Feature one
+- Feature two
+- Feature three
+
+## Documentation
+
+For detailed documentation, see [docs/](docs/).
+
+- [Getting Started](docs/guides/getting-started.md)
+- [Command Reference](docs/reference/commands/)
+- [Contributing](CONTRIBUTING.md)
+
+## Requirements
+
+- Requirement 1
+- Requirement 2
+
+## License
+
+[License type]
+```
+
+### Key Sections
+
+| Section | Required | Purpose |
+|---------|----------|---------|
+| Title & Description | Yes | What it is, one glance |
+| Installation | Yes | How to get it |
+| Quick Start | Recommended | Fastest path to value |
+| Features | Optional | What it does |
+| Documentation | Recommended | Where to learn more |
+| Requirements | When needed | Prerequisites |
+| License | Recommended | Legal |
+
+### Best Practices
+
+- Keep under 100 lines when possible
+- Lead with value: what does this do for me?
+- Show, don't just tell: include runnable examples
+- Link to docs/ for detailed information
+- Update when major features change
+
+## Directory README
+
+README.md files in subdirectories provide progressive disclosure.
+
+### Template
+
+```markdown
+# Directory Name
+
+Brief description of what this directory contains.
+
+## Contents
+
+- [file-one.md](file-one.md) - Description of file one
+- [file-two.md](file-two.md) - Description of file two
+- [subdirectory/](subdirectory/) - Description of subdirectory
+
+## Overview
+
+Optional 2-3 sentence overview if the contents list isn't self-explanatory.
+
+## See Also
+
+- [Related directory](../related/) - How it relates
+```
+
+### Key Principles
+
+1. **List contents first** - What's here?
+2. **Brief descriptions** - One line per item
+3. **Link everything** - Make it navigable
+4. **Keep it short** - Under 50 lines ideal
+5. **Update on changes** - Add/remove links as files change
+
+### When to Add a Directory README
+
+Add a README.md when:
+- Directory has 3+ files
+- Contents aren't obvious from names
+- Navigation would help readers
+- Providing context adds value
+
+Skip if:
+- Single file directory
+- File names are self-explanatory
+- Directory is transient/build output
+
+## Package README
+
+Metool packages require specific documentation.
+
+### Template
+
+```markdown
+# Package Name
+
+Brief description of what this package provides.
+
+## Installation
+
+\`\`\`bash
+mt package add module/package-name
+mt package install package-name
+\`\`\`
+
+## Components
+
+- `bin/tool-name` - What the tool does
+- `shell/functions` - Shell functions provided
+- `config/dot-file` - Configuration installed
+
+## Usage
+
+### Command Line
+
+\`\`\`bash
+tool-name [options] <args>
+\`\`\`
+
+### Shell Functions
+
+\`\`\`bash
+function_name arg1 arg2
+\`\`\`
+
+## Configuration
+
+Configuration file: `~/.config/package-name/config.yml`
+
+\`\`\`yaml
+option: value
+\`\`\`
+
+## Requirements
+
+- bash 4.0+
+- Other dependencies
+
+## See Also
+
+- [Related package](../related/) - How they work together
+```
+
+### Required Sections for Packages
+
+1. **Title and description** - What it does
+2. **Installation** - The two-step add + install
+3. **Components** - What gets installed
+4. **Usage** - How to use it
+5. **Requirements** - Dependencies if any
+
+## Examples
+
+### Good Project README
+
+```markdown
+# metool
+
+Package management for shell environments using GNU Stow.
+
+## Installation
+
+\`\`\`bash
+git clone https://github.com/mbailey/metool ~/.metool
+~/.metool/bin/mt bootstrap
+\`\`\`
+
+## Quick Start
+
+\`\`\`bash
+# Add and install a package
+mt package add dev/git-tools
+mt package install git-tools
+
+# List installed packages
+mt package list
+\`\`\`
+
+## Documentation
+
+See [docs/](docs/) for guides and reference.
+```
+
+### Good Directory README
+
+```markdown
+# Conventions
+
+Coding conventions and best practices for metool development.
+
+## Contents
+
+- [shell-scripting.md](shell-scripting.md) - Bash coding standards
+- [testing.md](testing.md) - How to write tests
+- [documentation/](documentation/) - Documentation standards
+- [package-structure.md](package-structure.md) - Package layout
+```
diff --git a/docs/conventions/documentation/root-documentation.md b/docs/conventions/documentation/root-documentation.md
new file mode 100644
index 0000000..a624552
--- /dev/null
+++ b/docs/conventions/documentation/root-documentation.md
@@ -0,0 +1,71 @@
+# Root Documentation Files
+
+Documentation files that live outside the `docs/` directory.
+
+## Overview
+
+All detailed documentation belongs in `docs/`. However, certain standard files live at the project root or in subdirectories. This file defines the complete list of allowed documentation files outside `docs/`.
+
+## Required Files
+
+| File | Location | Description |
+|------|----------|-------------|
+| README.md | Project root | Main entry point, overview, quick start |
+
+## Optional Standard Files
+
+### AI Agent Files
+
+| File | Location | Description |
+|------|----------|-------------|
+| AGENTS.md | Project root | AI agent instructions (industry standard) |
+| SKILL.md | Project root | Claude Code skill definition (makes package a skill) |
+| CLAUDE.md | Project root | Claude-specific instructions (reference AGENTS.md) |
+
+**AGENTS.md** is the emerging industry standard for AI coding assistants, supported by OpenAI Codex, Google Jules, Cursor, and others. Use it for project context, build steps, conventions, and boundaries.
+
+**SKILL.md** serves a different purpose - it makes a metool package discoverable as a Claude Code skill. It defines what the skill does and when to invoke it.
+
+**CLAUDE.md** is for Claude-specific instructions. Typically it should reference AGENTS.md and add any Claude-only configuration.
+
+### Project Files
+
+| File | Location | Description |
+|------|----------|-------------|
+| CONTRIBUTING.md | Project root | Contribution guidelines |
+| CHANGELOG.md | Project root | Version history |
+| LICENSE | Project root | License text (typically no extension) |
+
+## Directory READMEs
+
+| File | Location | Description |
+|------|----------|-------------|
+| README.md | Any directory | Navigation and context for directory contents |
+
+Directory READMEs serve progressive disclosure - they help readers understand what's in a directory and link to contents.
+
+## Validation
+
+To check for documentation files that don't match this convention:
+
+```bash
+# Find .md files outside docs/ that aren't on the allowed list
+find . -name "*.md" -not -path "./docs/*" \
+  | grep -v -E "(README|AGENTS|SKILL|CLAUDE|CONTRIBUTING|CHANGELOG)\.md$"
+```
+
+Any files found should either:
+1. Move to `docs/`
+2. Be added to this list (update the convention)
+
+## Notes
+
+- Prefer AGENTS.md for AI agent instructions (cross-tool compatible)
+- Use SKILL.md to make a package a Claude Code skill
+- CLAUDE.md can reference AGENTS.md for shared instructions
+- LICENSE typically has no `.md` extension
+- All other documentation content belongs in `docs/`
+
+## See Also
+
+- [AGENTS.md Standard](https://agents.md/) - Industry standard for AI coding agents
diff --git a/docs/conventions/documentation/writing-style.md b/docs/conventions/documentation/writing-style.md
new file mode 100644
index 0000000..deabdcb
--- /dev/null
+++ b/docs/conventions/documentation/writing-style.md
@@ -0,0 +1,284 @@
+# Writing Style
+
+Markdown formatting, tone, and style conventions for documentation.
+
+## Markdown Standards
+
+### Headers
+
+Use ATX-style headers with proper hierarchy:
+
+```markdown
+# Document Title
+
+## Major Section
+
+### Subsection
+
+#### Sub-subsection (use sparingly)
+```
+
+Rules:
+- One `#` per document
+- Don't skip levels (`#` then `###`)
+- Blank line before and after headers
+
+### Code Blocks
+
+Always specify the language:
+
+````markdown
+```bash
+mt install package-name
+```
+
+```python
+def example():
+    pass
+```
+
+```yaml
+key: value
+```
+````
+
+For inline code, use single backticks: `mt install`
+
+### Lists
+
+Consistent markers, proper nesting:
+
+```markdown
+- First item
+- Second item
+  - Nested item
+  - Another nested item
+- Third item
+
+1. Numbered item
+2. Another numbered item
+   - Can mix bullets in numbered lists
+3. Final numbered item
+```
+
+### Tables
+
+Use for structured data:
+
+```markdown
+| Column 1 | Column 2 | Column 3 |
+|----------|----------|----------|
+| Data     | Data     | Data     |
+```
+
+Align columns for readability in source.
+
+### Links
+
+Descriptive link text:
+
+```markdown
+# Good
+See [Shell Scripting Conventions](shell-scripting.md) for details.
+
+# Bad
+Click [here](shell-scripting.md) for more.
+```
+
+Use relative paths for internal links.
+
+## Tone and Voice
+
+### Active Voice
+
+Write in active voice:
+
+```markdown
+# Good
+The command creates a symlink.
+Run the script to start.
+
+# Avoid
+A symlink is created by the command.
+The script should be run to start.
+```
+
+### Present Tense
+
+Use present tense:
+
+```markdown
+# Good
+Returns the path to the module.
+The function accepts two arguments.
+
+# Avoid
+Will return the path to the module.
+The function accepted two arguments.
+```
+
+### Imperative for Instructions
+
+Use imperative form for steps:
+
+```markdown
+# Good
+1. Install the package.
+2. Edit the configuration.
+3. Restart the service.
+
+# Avoid
+1. You should install the package.
+2. The configuration should be edited.
+```
+
+### Be Concise
+
+- Short, clear sentences
+- Remove unnecessary words
+- Get to the point quickly
+
+```markdown
+# Good
+Install with `mt install package`.
+
+# Wordy
+In order to install the package, you can use the mt install command.
+```
+
+## Special Sections
+
+### Warnings
+
+```markdown
+> **Warning**: This command deletes files permanently.
+```
+
+### Notes
+
+```markdown
+> **Note**: Requires bash 4.0 or later.
+```
+
+### Tips
+
+Use details for optional content:
+
+```markdown
+<details>
+<summary>Tip: Speed up searches</summary>
+
+Use specific patterns to reduce search time.
+
+</details>
+```
+
+## Code Comments
+
+### Function Documentation
+
+Document at the function definition:
+
+```bash
+# Get the path to a metool module
+# $1 - Module name
+# Returns: Path to module directory
+# Example: path=$(get_module_path "public")
+get_module_path() {
+    local module="$1"
+    # Implementation
+}
+```
+
+### Inline Comments
+
+Explain why, not what:
+
+```bash
+# Good: explains the reason
+# Use read to handle paths with spaces correctly
+read -r path <<< "$output"
+
+# Bad: restates the obvious
+# Read the path variable
+read -r path <<< "$output"
+```
+
+## Examples
+
+### Good Examples
+
+- Show common use cases first
+- Include expected output when helpful
+- Explain what each example does
+
+```markdown
+```bash
+# Install a package from the dev module
+mt package add dev/git-tools
+mt package install git-tools
+
+# List installed packages
+mt package list
+# Output:
+#   git-tools  /path/to/git-tools
+#   tmux       /path/to/tmux
+```
+```
+
+### Avoid
+
+- `foo`, `bar`, `baz` unless truly generic
+- Overly complex examples
+- Hardcoded paths like `/home/user/`
+
+## Consistency
+
+### Terminology
+
+Use consistent terms throughout:
+
+| Use | Don't Use |
+|-----|-----------|
+| package | pkg, module (when meaning package) |
+| directory | folder (except in GUI context) |
+| run | execute |
+| file | doc (when meaning file) |
+
+### Formatting
+
+| Element | Format |
+|---------|--------|
+| Commands | `backticks` |
+| File paths | `backticks` |
+| Placeholders | `<angle-brackets>` |
+| Optional | `[square-brackets]` |
+| Keys/buttons | **Bold** |
+
+## File Organization
+
+### When to Split
+
+Create separate files when:
+- Section exceeds ~50 lines
+- Topic is self-contained
+- Different audiences need different content
+- Multiple subtopics exist
+
+### File Headers
+
+Start each file with:
+
+```markdown
+# Clear Title
+
+Brief description of what this document covers.
+
+## Contents or first section
+```
+
+### Line Length
+
+- No hard limit, but prefer under 100 characters
+- Break long lines in lists for readability
+- Don't break code blocks artificially