docs(docs): add initial docs baseline

.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
 ```

.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
 

.github/etc/dictionary.txt

@@ -1,7 +1,14 @@
 allstar
+anchore
+buildx
 cookiecutter
 dependabot
 digestabot
+dockerhub
+envrc
+htmlcov
+pylance
+pythonpath
 refurb
 skopeo
 syft

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

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
 

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
-```

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).

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.

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.

FAQ.md → 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