diff --git a/.cursor/rules/python-template.mdc b/.cursor/rules/python-template.mdc
index 1c6e8d0..9d70e92 100644
--- a/.cursor/rules/python-template.mdc
+++ b/.cursor/rules/python-template.mdc
@@ -7,17 +7,21 @@ type: always
 You are working on a cookiecutter template for generating modern Python projects.
 
 ## Critical Context
-This is a TEMPLATE GENERATOR. Files in `{{cookiecutter.project_name}}/` contain Jinja2 variables that must be preserved exactly as written.
+
+This is a TEMPLATE GENERATOR. Files in `{{cookiecutter.project_name ...}}/` contain Jinja2 variables that must be preserved exactly as written.
 
 ## Tech Stack
+
 - Python 3.13+ with uv package manager (NOT pip/poetry)
 - pytest with >80% coverage requirement
 - Pre-commit: ruff, pyright, refurb
 - Security: grype, syft
 - CI/CD: GitHub Actions
-- Versioning: CalVer or SemVer-ish
+
+6. Update documentation in the docs/ directory as features are added or changed
 
 ## Code Standards
+
 - Max line length: 120
 - Type hints required
 - Google-style docstrings
@@ -26,6 +30,7 @@ This is a TEMPLATE GENERATOR. Files in `{{cookiecutter.project_name}}/` contain
 - Specific exception handling
 
 ## Key Commands
+
 ```bash
 task init       # Setup environment
 task build      # Build project
@@ -34,7 +39,9 @@ task lint       # Check code quality
 ```
 
 ## Template Testing
+
 ```bash
-uvx cookiecutter .    # Generate project
-pytest tests/         # Test template
+uvx --with gitpython cookiecutter . --no-input    # Generate a default project
+cd $(ls -td * | head -1)
+task init test                                    # Test the template
 ```
diff --git a/.github/CONTRIBUTING.md b/.github/CODE_OF_CONDUCT.md
similarity index 100%
rename from .github/CONTRIBUTING.md
rename to .github/CODE_OF_CONDUCT.md
diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
index 3fc2e2d..1896f00 100644
--- a/.github/copilot-instructions.md
+++ b/.github/copilot-instructions.md
@@ -6,10 +6,8 @@ built-in.
 ## Context
 
 - This is a **template generator**, not a regular Python project
-- Files in `{{cookiecutter.project_name}}` directory contain Jinja2 template variables
+- Files in the `{{cookiecutter.project_name ... }}` directory contain Jinja2 template variables
 - The project uses `uv` as the package manager (not pip or poetry)
-- Python 3.13+ is the minimum requirement
-- The template uses python-semantic-release for automated versioning
 
 ## Code Conventions
 
@@ -60,7 +58,7 @@ Common tasks are automated via Taskfile:
 3. Follow the established project structure
 4. Include appropriate error handling
 5. Add tests for new functionality
-6. Update documentation as needed
+6. Update documentation in the docs/ directory as features are added or changed
 
 ## Template-Specific Guidelines
 
diff --git a/.github/etc/dictionary.txt b/.github/etc/dictionary.txt
index ac9b72d..577a36a 100644
--- a/.github/etc/dictionary.txt
+++ b/.github/etc/dictionary.txt
@@ -1,7 +1,14 @@
 allstar
+anchore
+buildx
 cookiecutter
 dependabot
 digestabot
+dockerhub
+envrc
+htmlcov
+pylance
+pythonpath
 refurb
 skopeo
 syft
diff --git a/CLAUDE.md b/CLAUDE.md
index f618381..b3e1adc 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -55,13 +55,10 @@ This is a **template generator** that creates Python projects with:
 task init
 
 # Run tests and linting
-task build test
+task lint build test
 
 # Generate a project from template
-uvx cookiecutter .
-
-# Test template with default values
-pytest tests/
+uvx --with gitpython cookiecutter .
 ```
 
 ## When Making Changes
@@ -71,6 +68,7 @@ pytest tests/
 3. **Test Thoroughly**: Both template and generated projects
 4. **Document Changes**: Update relevant documentation
 5. **Security First**: No hardcoded secrets, follow OWASP guidelines
+6. **Maintain Documentation**: When making changes to features, update the corresponding documentation in the `docs/` folder
 
 ## Template Variables
 
@@ -134,6 +132,10 @@ def test_template_generation(cookies):
 4. Keep dependencies updated
 5. Follow principle of least privilege
 
+## Documentation Structure
+
+The project documentation is organized in the `docs/` folder. When modifying any feature documented above, ensure the corresponding documentation is updated.
+
 ## Helpful Context
 
 - The template is designed for "vibe coding" - AI assistants should understand patterns without verbose prompts
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 240ef40..dcfce46 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -1,8 +1,9 @@
 # Contributing
 
-To contribute to this project, please fork the repository and open a pull request with your changes.
+To contribute to this project, please consider starting by [opening an issue](https://github.com/Zenable-io/ai-native-python/issues/new) to discuss the feature
+and its design, and reviewing our Contributors Code of Conduct [here](./.github/CODE_OF_CONDUCT.md).
 
-Also, see our Contributors Code of Conduct [here](./.github/CONTRIBUTING.md).
+Once you are ready to submit your contribution, please fork the repository and open a pull request with your changes.
 
 ## Updating the dependencies
 
diff --git a/README.md b/README.md
index 5f380d3..31bbafb 100644
--- a/README.md
+++ b/README.md
@@ -19,7 +19,7 @@ Make your tools meet every requirement on the first pass, letting you ship faste
 - 📦 Ensure usability across all major platforms with multi-platform Docker builds
 - 🔄 Automated versioning and releasing with `python-semantic-release`
 
-For FAQs including release workflow troubleshooting, see our [FAQ documentation](./FAQ.md)
+For more details, see our [documentation](docs/index.md).
 
 ## Getting Started
 
@@ -61,13 +61,3 @@ git checkout -b initial-content
 # Check for `NotImplementedError`s and address them as a part of adding your business logic
 grep -r NotImplementedError *
 ```
-
-### Optional setup
-
-If you'd like to support license file checking locally, you will need to install `grant` and put it in your `PATH`
-
-Additionally, if you'd like to use SSH instead of HTTPS to connect to the `ai-native-python` project, use this command instead:
-
-```bash
-uvx --with gitpython cookiecutter git+ssh://git@github.com/zenable-io/ai-native-python.git
-```
diff --git a/docs/ai-ide-support.md b/docs/ai-ide-support.md
new file mode 100644
index 0000000..ee59b65
--- /dev/null
+++ b/docs/ai-ide-support.md
@@ -0,0 +1,46 @@
+# AI IDE Support
+
+The AI-Native Python template includes configuration files to work seamlessly with AI-powered development tools.
+
+[← Back to Documentation Index](index.md)
+
+
+## Tool-agnostic configurations
+
+### .mcp.json
+
+Model Context Protocol configuration pre-set to integrate with:
+
+- [Zenable](https://zenable.io)'s MCP server
+- [Context7](https://context7.com/)'s MCP server
+
+## Specific IDE configurations
+
+### Claude Code
+
+Every generated project includes a `CLAUDE.md` file with:
+
+- Project-specific context and guidelines
+- Technology stack information
+- Code style rules and patterns
+- Common tasks and workflows
+
+### GitHub Copilot Configuration
+
+The template includes `.github/copilot-instructions.md` with:
+
+- Project-specific context for GitHub Copilot
+- Code conventions and patterns
+- Testing requirements and workflow
+- Security considerations
+- Common code patterns and examples
+- Task automation commands
+
+### Cursor IDE Configuration
+
+The template includes `.cursor/rules/` directory with:
+
+- `project.mdc`: Always-active rules with project info, tech stack, and key commands
+- `testing.mdc`: Auto-attached rules for test files with testing guidelines and patterns
+
+For more details on testing configuration and practices, see the [Testing Guide](testing.md).
diff --git a/docs/ci-cd.md b/docs/ci-cd.md
new file mode 100644
index 0000000..61b6c56
--- /dev/null
+++ b/docs/ci-cd.md
@@ -0,0 +1,46 @@
+# CI/CD Workflows
+
+The AI-Native Python template includes GitHub Actions workflows for automated testing, security scanning, and release management.
+
+[← Back to Documentation Index](index.md)
+
+## Included Workflows
+
+### CI Pipeline (`.github/workflows/ci.yml`)
+
+Runs on every push and pull request:
+
+1. **Linting** - Python (Ruff), YAML/JSON, shell scripts, GitHub Actions
+2. **Testing** - Unit and integration tests with >80% coverage requirement, as well as docker builds on each supported platform
+3. **Security** - Vulnerability scanning (Grype), SBOM generation (Syft), secret detection
+
+### Release Pipeline (`.github/workflows/release.yml`)
+
+Automates semantic versioning and publishing:
+
+1. Analyzes commit messages to determine version bump
+2. Updates version in `pyproject.toml`
+3. Generates changelog
+4. Creates GitHub release
+5. Pushes Docker images to Docker Hub (if enabled)
+
+### PR Validation (`.github/workflows/pr.yml`)
+
+Ensures pull request quality:
+
+- Validates PR title follows conventional commit format
+- Checks all commit messages
+- Look for deprecations or warnings and adds them to the finalizer
+
+## Configuration
+
+For GitHub Actions configuration and required secrets, see the [Configuration Guide](configuration.md#post-generation-configuration).
+
+### Dependency Updates
+
+The generated project includes multiple dependency update mechanisms. See the [Configuration Guide](configuration.md#post-generation-configuration) for details
+on customizing these tools.
+
+## Customization
+
+Add new workflows in `.github/workflows/` for specific needs like deployment or scheduled tasks.
diff --git a/docs/configuration.md b/docs/configuration.md
new file mode 100644
index 0000000..3c984c6
--- /dev/null
+++ b/docs/configuration.md
@@ -0,0 +1,81 @@
+# Configuration Guide
+
+This guide covers the configuration options available in the AI-Native Python cookiecutter template.
+
+[← Back to Documentation Index](index.md)
+
+## Cookiecutter Variables
+
+When generating a new project, you'll be prompted for the following configuration options:
+
+### Basic Project Information
+
+| Variable                    | Description                      | Default        | Example                     |
+| --------------------------- | -------------------------------- | -------------- | --------------------------- |
+| `project_name`              | Human-readable project name      | (required)     | "My Awesome Project"        |
+| `project_slug`              | Python package name (snake_case) | Auto-generated | "my_awesome_project"        |
+| `project_short_description` | Brief project description        | (required)     | "A tool for awesome things" |
+
+### Organization Details
+
+| Variable                        | Description                     | Default    | Example     |
+| ------------------------------- | ------------------------------- | ---------- | ----------- |
+| `company_name`                  | Your organization's name        | (required) | "Acme Corp" |
+| `company_domain`                | Your organization's domain      | (required) | "acme.com"  |
+| `github_org`                    | GitHub organization or username | (required) | "acme-corp" |
+| `project_owner_github_username` | Project owner's GitHub username | (required) | "johndoe"   |
+
+### Technical Options
+
+| Variable         | Description                  | Default | Options                       |
+| ---------------- | ---------------------------- | ------- | ----------------------------- |
+| `python_version` | Minimum Python version       | "3.13"  | "3.11", "3.12", "3.13"        |
+| `dockerhub`      | Enable Docker Hub publishing | "no"    | "yes", "no"                   |
+| `public`         | Make repository public       | "yes"   | "yes", "no"                   |
+| `license`        | Project license              | "NONE"  | "NONE", "MIT", "BSD-3-Clause" |
+
+## Post-Generation Configuration
+
+After your project is generated, you are able to make any changes you'd like. Here are some common modifications:
+
+### Environment Variables
+
+Create or modify the `.envrc` file in your project root:
+
+```bash
+# API Keys
+export ZENABLE_API_KEY="your-api-key-here"
+
+# Development settings
+export PYTHONPATH="${PWD}/src:${PYTHONPATH}"
+export UV_PYTHON_PREFERENCE="only-system"
+```
+
+### Task Configuration
+
+The `Taskfile.yml` in your project defines common development tasks. You can customize anything you'd like, such as:
+
+- Python versions
+- Linting and cleanup tasks
+- Build configurations
+
+Example task customization:
+
+```yaml
+vars:
+  IMAGE_NAME: "abc123"    # Change the name of the docker image
+  PYTHON_VERSION: "3.13"  # Change default Python version
+```
+
+### Pre-commit Hooks
+
+For detailed information about pre-commit hooks configuration and available hooks, see the [Hooks Guide](hooks.md#pre-commit-hooks).
+
+#### Docker Hub Secrets
+
+If you enabled Docker Hub publishing:
+
+- `DOCKERHUB_USERNAME`
+- `DOCKERHUB_PAT`
+
+A reminder to set this is also printed after project generation if you answered "yes" to the docker hub question.
diff --git a/FAQ.md b/docs/faq.md
similarity index 83%
rename from FAQ.md
rename to docs/faq.md
index ba087f7..f292002 100644
--- a/FAQ.md
+++ b/docs/faq.md
@@ -1,5 +1,7 @@
 # Frequently Asked Questions
 
+[← Back to Documentation Index](index.md)
+
 ## Version Control System support
 
 ### Q: Do you support version control platforms other than GitHub?
@@ -10,7 +12,8 @@
 
 ### Q: Why is my release workflow failing with permission errors?
 
-**A:** The release workflow requires the GitHub Actions bot to have permission to push commits to the main branch. This is necessary because semantic-release creates a commit to update version numbers in files.
+**A:** The release workflow requires the GitHub Actions bot to have permission to push commits to the main branch. This is necessary because semantic-release
+creates a commit to update version numbers in files.
 
 #### Solution:
 
@@ -36,16 +39,6 @@ If you've already generated the project and just want to fix it up from here, fo
    - The organization may need to explicitly grant the GitHub Actions app permission to push
    - Contact your organization administrators if default permissions are restricted
 
-### Q: Why does semantic-release fail with "no commits to release"?
-
-**A:** Semantic-release uses conventional commits to determine the next version. If there are no commits following the conventional commit format since the last release, it won't create a new release.
-
-Ensure your commits follow the format:
-- `feat:` for new features (triggers minor version bump)
-- `fix:` for bug fixes (triggers patch version bump)
-- `BREAKING CHANGE:` in the commit body (triggers major version bump)
-- Other types like `docs:`, `chore:`, `style:` don't trigger releases
-
 ### Q: Can I manually specify the version number?
 
 **A:** No, the workflow is designed to automatically determine the version based on conventional commits. This ensures consistent versioning across all
diff --git a/docs/hooks.md b/docs/hooks.md
new file mode 100644
index 0000000..60f17a4
--- /dev/null
+++ b/docs/hooks.md
@@ -0,0 +1,75 @@
+# Hooks
+
+The AI-Native Python template uses hooks to automate setup tasks automatically.
+
+[← Back to Documentation Index](index.md)
+
+## Cookiecutter Hooks
+
+### Post-Generation Hook
+
+The `post_gen_project.py` hook runs after project generation to:
+
+1. Initialize the project as a Git repository
+2. Create the project's initial commit
+3. Set up GitHub remote (if credentials available)
+4. Generate a fully up-to-date `uv.lock` file
+5. Create an `.envrc` with API keys
+6. Run `task init` to install dependencies
+7. Push to GitHub and create an initial release
+
+### Configuration
+
+Environment variables can be set before running cookiecutter to modify hook behavior:
+
+- `SKIP_GIT_PUSH=true` - Skip automatic Git push
+- `RUN_POST_HOOK=false` - Skip the post-generation hook entirely (not recommended)
+- `ZENABLE_API_KEY="..."` - Auto-populate API key in .envrc
+
+For more environment variable options, see the [Optional Setup Guide](optional-setup.md#environment-variable-configuration).
+
+## Pre-commit Hooks
+
+Automatically run code quality checks before each commit.
+
+### Installation
+
+```bash
+task init  # Installs pre-commit and sets up hooks, alongside setting up other project dependencies to get started
+```
+
+### Included Hooks
+
+1. **Python** - Ruff for linting and formatting
+2. **Security** - Trufflehog for secret detection
+3. **File Checks** - JSON/YAML validation, large files, merge conflicts
+4. **Spell Check** - Typos with custom dictionary
+5. **Shell Scripts** - ShellCheck validation
+6. **GitHub Actions** - Actionlint validation
+7. **OpenAPI** - Schema validation
+
+For the full list of hooks, see `{{cookiecutter.project_name|replace(" ", "")}}/.pre-commit-config.yaml`
+
+### Configuration
+
+Edit `.pre-commit-config.yaml` to customize:
+
+```yaml
+- repo: https://github.com/astral-sh/ruff-pre-commit
+  rev: v0.8.6
+  hooks:
+    - id: ruff
+      args: [--fix, --show-fixes]
+```
+
+### Adding Custom Hooks
+
+```yaml
+- repo: local
+  hooks:
+    - id: pytest-check
+      name: pytest-check
+      entry: pytest
+      language: system
+      pass_filenames: false
+```
diff --git a/docs/index.md b/docs/index.md
new file mode 100644
index 0000000..f912909
--- /dev/null
+++ b/docs/index.md
@@ -0,0 +1,33 @@
+# AI-Native Python Documentation
+
+Welcome to the AI-Native Python documentation. This guide will help you understand and use the AI-Native Python cookiecutter template effectively.
+
+## Documentation Structure
+
+### Getting Started
+- [Configuration Guide](configuration.md) - Cookiecutter variables and post-generation setup
+- [Optional Setup](optional-setup.md) - Additional tools and configurations
+
+### Development Workflow
+- [AI IDE Support](ai-ide-support.md) - such as configuring Claude, Copilot, Cursor, or other IDEs
+- [Testing](testing.md) - Test structure, running tests, and coverage
+- [Hooks](hooks.md) - Cookiecutter and pre-commit hooks
+
+### Automation & Deployment
+- [CI/CD Workflows](ci-cd.md) - GitHub Actions pipelines and automation
+- [FAQ](faq.md) - Common issues and solutions
+
+### Future Development
+- [Roadmap](roadmap.md) - Planned features and improvements
+
+## Quick Links
+
+- [Main README](../README.md)
+- [Contributing Guidelines](../CONTRIBUTING.md)
+- [GitHub Repository](https://github.com/zenable-io/ai-native-python)
+
+## Need Help?
+
+If you encounter issues not covered in these docs:
+1. Check the [FAQ](faq.md)
+2. [Open an issue](https://github.com/zenable-io/ai-native-python/issues/new)
diff --git a/docs/optional-setup.md b/docs/optional-setup.md
new file mode 100644
index 0000000..90f8b3a
--- /dev/null
+++ b/docs/optional-setup.md
@@ -0,0 +1,55 @@
+# Optional Setup Guide
+
+This guide covers optional setup steps and configurations for the AI-Native Python template.
+
+[← Back to Documentation Index](index.md)
+
+## Grant Installation (License Compliance)
+
+If you'd like to support license file checking locally, you will need to install `grant` and put it in your `PATH`. See [their installation
+guide](https://github.com/anchore/grant?tab=readme-ov-file#installation) for more details
+
+## SSH Configuration for Cookiecutter
+
+If you prefer to use SSH instead of HTTPS for cloning the template, you can use the SSH URL.
+
+### Prerequisites
+
+1. SSH key configured with GitHub:
+
+   ```bash
+   # Check for existing SSH keys
+   ls -la ~/.ssh
+
+   # Generate new SSH key if needed
+   ssh-keygen -t ed25519 -C "your_email@example.com"
+   ```
+
+2. Add SSH key to GitHub:
+
+   ```bash
+   # Copy public key
+   cat ~/.ssh/id_ed25519.pub
+   # Add to GitHub: Settings -> SSH and GPG keys
+   ```
+
+3. Test SSH connection:
+
+   ```bash
+   ssh -T git@github.com
+   ```
+
+### Using SSH with Cookiecutter
+
+```bash
+# Use SSH URL instead of HTTPS
+uvx --with gitpython cookiecutter git+ssh://git@github.com/zenable-io/ai-native-python.git
+```
+
+## Environment Variable Configuration
+
+Generated projects include an `.envrc` file for environment-specific settings. API keys can be pre-populated during project generation by setting environment
+variables before running cookiecutter (see the [Hooks Guide](hooks.md#configuration)).
+
+To request support for additional API keys, please [open an issue](https://github.com/Zenable-io/ai-native-python/issues/new) or [pull
+request](../CONTRIBUTING.md)!
diff --git a/ROADMAP.md b/docs/roadmap.md
similarity index 90%
rename from ROADMAP.md
rename to docs/roadmap.md
index bcda404..119aa24 100644
--- a/ROADMAP.md
+++ b/docs/roadmap.md
@@ -2,6 +2,8 @@
 
 This document outlines future improvements and enhancements for the ai-native-python project.
 
+[← Back to Documentation Index](index.md)
+
 ## Ideas
 
 ### 1. Add Policy as Code
@@ -15,6 +17,7 @@ This document outlines future improvements and enhancements for the ai-native-py
 
 - Keep the public yes/no but split out a CodeQL yes/no (default to yes; secure by default but it may error if insufficient licensing)
 - Improve the docs around releasing and rulesets/branch protections
+- Add support for releasing to pypi via oidc
 
 ### 3. Improve project health checks
 
@@ -65,10 +68,4 @@ We welcome community feedback and contributions. Some areas where we'd especiall
 
 ## Contributing
 
-If you're interested in contributing to any of these roadmap items, please:
-
-1. Open an issue to discuss the feature
-2. Submit a pull request with your implementation
-3. Update this roadmap as items are completed
-
-For more information, see [CONTRIBUTING.md](.github/CONTRIBUTING.md)
+If you're interested in contributing to any of these roadmap items, please see our [contribution guide](../CONTRIBUTING.md), and thank you! 🎉
diff --git a/docs/testing.md b/docs/testing.md
new file mode 100644
index 0000000..f6c496d
--- /dev/null
+++ b/docs/testing.md
@@ -0,0 +1,63 @@
+# Testing Guide
+
+This document covers two distinct testing contexts:
+
+1. **Template Tests** - Tests for the AI-Native Python cookiecutter template itself (i.e. this repository)
+2. **Generated Project Tests** - Tests included in projects created from this template (i.e. projects rendered after running `cookiecutter`)
+
+[← Back to Documentation Index](index.md)
+
+## Template Tests
+
+These tests ensure the cookiecutter template works correctly and generates valid projects.
+
+### Running Template Tests
+
+```bash
+# From this repository
+task test               # Run all template tests with coverage
+task unit-test          # Run unit tests only
+task integration-test   # Run integration tests only
+```
+
+### What Template Tests Cover
+
+- **Generation Validation**: Tests with various input combinations to ensure valid project generation
+- **Hook Execution**: Verifies post-generation hooks run correctly
+- **File Structure**: Confirms all expected files are created
+- **End-to-End**: Full test of the default parameter answers including:
+  - Project initialization
+  - Dependency installation
+  - Running generated project's test suite and linters
+
+## Generated Project Tests
+
+Every project created from this template includes a complete testing setup.
+
+### Features Included
+
+- **100% Coverage**: Template provides tests for the initial `main.py` and module code
+- **Pytest Configuration**: Pre-configured in `pyproject.toml`
+- **Coverage Requirements**: 80% minimum enforced in CI/CD
+
+### Running Tests in Generated Projects
+
+```bash
+# From the generated project root
+task test                    # Run all tests with coverage
+task unit-test               # Run unit tests only
+task integration-test        # Run integration tests only
+```
+
+### Writing Tests in Generated Projects
+
+Generated projects use pytest with:
+
+- Parametrized tests for multiple scenarios
+- Markers for test categorization (`@pytest.mark.unit`, `@pytest.mark.integration`)
+- Mocking for external dependencies
+
+## CI/CD Integration
+
+The above tests are a part of what's automatically executed in the CI pipeline. For complete details on test automation and workflow configuration, see the
+[CI/CD Guide](ci-cd.md#ci-pipeline-githubworkflowsciyml).