+
+Welcome to the {{project_name}} template repository! This template provides a robust foundation for building high-quality, scalable software projects. It includes standard directories, issue templates, CI/CD workflows, and comprehensive placeholder documentation.
+
+To use this template, simply find and replace all instances of `{{project_name}}` and `{{organization}}` with your actual project details, update the placeholder SVG images in `docs/assets/branding/`, and you are ready to start coding.
+
+### Why Use {{project_name}}?
+
+- **Consistency:** Enforces a standardized layout and structure across your organization's repositories.
+- **Speed:** Bootstraps your project with pre-configured Actions, badges, and templates so you don't start from scratch.
+- **Best Practices:** Baked-in guides for contributing, security, and developer setup.
+
+### Comparisons
+
+When evaluating {{project_name}} against other templates, consider the following differences:
+
+| Feature | {{project_name}} Template | Standard GitHub Init | Cookiecutter / Copier |
+| :--- | :--- | :--- | :--- |
+| **Setup Speed** | Very Fast | Fast | Slower (requires CLI tool) |
+| **Visual Assets** | Pre-configured Light/Dark assets | None | Varies |
+| **CI/CD Built-in** | Yes (GitHub Actions) | No | Optional |
+| **Complexity** | Low (Find and Replace) | None | Medium (Jinja templates) |
+
+
+## What's New
+
+**Welcome to the {{project_name}} Launch!**
+
+This project has just been instantiated from the template repository. Keep an eye on this section for future release highlights, new features, and community announcements!
+
+
+
+## Quick Start
+
+```bash
+
+# e.g., npm install {{project_name}} OR pip install {{project_name}} OR cargo add {{project_name}}
+```
+
+For full installation options (from source, Docker, platform-specific notes) and step-by-step onboarding, see the **[Getting Started guide](https://{{organization}}.github.io/{{project_name}}/getting-started/)**.
+
+## Core Concepts
+
+
+
+### Component Architecture
+
+The template is organized into several key areas:
+- `docs/`: Stores your documentation and branding assets.
+- `src/` (or your primary package directory): The core application logic.
+- `tests/`: Automated tests to ensure code quality.
+
+## Advanced Usage
+
+
+
+## General
+
+### Contributing
+
+We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for more details. For development setup, check out [DEVELOPING.md](DEVELOPING.md).
+Please ensure you follow our [Code of Conduct](CODE_OF_CONDUCT.md) in all interactions.
+
+### Support and Security
+
+- For help and general questions, see [SUPPORT.md](SUPPORT.md).
+- To report a security vulnerability, please refer to our [Security Policy](SECURITY.md).
+
+### AI & LLM Tooling
+
+This repository includes first-class support for agentic and LLM-assisted development workflows:
+
+- **[AGENTS.md](AGENTS.md):** Repository-specific instructions for AI coding agents (Codex, Copilot Workspace, Gemini, Claude, Cursor, and similar tools). Contains the authoritative guide for project structure, executable commands, code style, and critical constraints.
+- **[llms.txt](llms.txt):** A machine-readable index of the project's documentation, following the [llms.txt specification](https://llmstxt.org/). Served at `/llms.txt` on the documentation site to help LLMs quickly locate and consume relevant content.
+
+### License
+
+This project is licensed under the Apache License 2.0. See the [LICENSE](LICENSE) file for details.
+
+### Citations
+
+If you use this template or the resulting software in your research, please cite it using the following BibTeX entry:
+
+```bibtex
+@software{{{project_name}},
+ author = {{{organization}}},
+ title = {{{project_name}}},
+ version = {{{version}}},
+ month = {{{month}}},
+ year = {2026},
+ url = {https://github.com/{{organization}}/{{project_name}}}
+}
+```
diff --git a/SECURITY.md b/SECURITY.md
new file mode 100644
index 0000000..a999843
--- /dev/null
+++ b/SECURITY.md
@@ -0,0 +1,56 @@
+# Security Policy for `{{project_name}}`
+
+We take the security of `{{project_name}}` seriously. This document outlines our security policies, supported versions, and how to responsibly disclose a vulnerability.
+
+## Supported Versions
+
+Please check the table below for the versions of `{{project_name}}` that are currently being supported with security updates.
+
+| Version | Supported |
+| :--- | :--- |
+| `{{current_major_version}}.x` | :white_check_mark: |
+| `< {{current_major_version}}.0` | :x: |
+
+*(Note: Replace the table contents with your actual versioning scheme once released.)*
+
+## Reporting a Vulnerability
+
+> [!IMPORTANT]
+> **Please do not report security vulnerabilities through public GitHub issues, discussions, or pull requests.**
+
+If you discover a security vulnerability, please bring it to our attention right away using one of the following methods:
+
+1. **GitHub Security Advisories (Preferred):** Use the "Report a vulnerability" button on the **[Security tab](https://github.com/{{organization}}/{{project_name}}/security/advisories)** of this repository.
+2. **Email:** Send your report directly to **[INSERT EMAIL ADDRESS OR SECURITY CONTACT]**. *(Optional: Encrypt your email using our PGP key: [INSERT PGP KEY LINK/FINGERPRINT])*
+
+### What to Include in Your Report
+
+To help us resolve the issue quickly, please include the following information:
+- **Type of vulnerability** (e.g., XSS, SQLi, RCE, authorization bypass).
+- **Detailed description** of the vulnerability and its potential impact.
+- **Step-by-step instructions** to reproduce the issue.
+- **Proof of Concept (PoC)** code or screenshots, if available.
+- **Environment details** (e.g., version of `{{project_name}}`, OS, relevant configurations).
+
+## Triage and Resolution Process
+
+We will handle your report with strict confidentiality. Our process is as follows:
+
+1. **Acknowledgment:** We will respond to your report as soon as possible, usually within **[INSERT NUMBER, e.g., 48] hours**.
+2. **Triage:** We will investigate the issue and determine its validity and severity. We may contact you for further clarification.
+3. **Fix:** If the vulnerability is verified, we will develop and test a patch.
+4. **Disclosure:** We will coordinate with you to publicly disclose the vulnerability once a fix is released. We will publicly acknowledge your responsible disclosure, if you wish.
+
+## Scope
+
+**In Scope:**
+- Vulnerabilities within the core `{{project_name}}` codebase.
+- Security issues in our default configurations.
+
+**Out of Scope:**
+- Volumetric Denial of Service (DoS) attacks.
+- Theoretical issues without a reproducible PoC.
+- Vulnerabilities in third-party dependencies that are not exploitable through `{{project_name}}`.
+- Missing security headers or best practices that do not lead to a direct exploit.
+
+*(Note: We currently **[do/do not]** operate a bug bounty program. Disclosures are greatly appreciated but are not eligible for financial rewards at this time.)*
diff --git a/SUPPORT.md b/SUPPORT.md
new file mode 100644
index 0000000..dd8714d
--- /dev/null
+++ b/SUPPORT.md
@@ -0,0 +1,41 @@
+# Support for `{{project_name}}`
+
+We are excited to have you use `{{project_name}}`! If you need help, please follow these guidelines to ensure you get support quickly and efficiently.
+
+## Security Vulnerabilities
+
+> [!IMPORTANT]
+> **Please do not report security vulnerabilities through public GitHub issues.**
+
+If you have found a security vulnerability, please refer to our [Security Policy](SECURITY.md) for instructions on how to securely report it.
+
+## Where to Find Help
+
+Before reaching out, we recommend checking the following resources. Many common questions and issues are already covered there.
+
+- **[Official Documentation](https://{{organization}}.github.io/{{project_name}}):** Comprehensive guides, tutorials, and API references.
+- **[GitHub Issues](https://github.com/{{organization}}/{{project_name}}/issues):** Search existing issues to see if someone else has already reported your problem or requested your feature. Feel free to add a "+1" reaction to existing issues to show your interest.
+- **[GitHub Discussions](https://github.com/{{organization}}/{{project_name}}/discussions):** Search our discussions for Q&A, general advice, and community knowledge.
+
+## Opening a New Issue
+
+If you cannot find an answer in the documentation or existing issues, please open a new issue. To help us resolve your issue faster, please choose the correct venue:
+
+| Issue Type | Venue | Description |
+| :--- | :--- | :--- |
+| **Bug Report** | [GitHub Issues](https://github.com/{{organization}}/{{project_name}}/issues/new) | Use the "Bug Report" template. Provide reproducible steps, environment details, and relevant logs. |
+| **Feature Request** | [GitHub Issues](https://github.com/{{organization}}/{{project_name}}/issues/new) | Use the "Feature Request" template. Clearly describe your use case and the problem the feature would solve. |
+| **Q&A / General Help** | [GitHub Discussions](https://github.com/{{organization}}/{{project_name}}/discussions/new) | Start a discussion for questions about how to use `{{project_name}}`, architecture queries, or advice. |
+
+## Community Channels
+
+Join our community to chat with other users, contributors, and the core maintainers:
+
+- **[Discord / Slack / Matrix - Insert Link]**: Join our real-time chat server.
+- **[Mailing List / Forum - Insert Link]**: Subscribe for announcements and longer-form discussions.
+- **[Weekly Syncs - Insert Link]**: Join our community meetings (see our calendar for details).
+
+## Commercial Support
+
+
+At this time, there is no official commercial support available for `{{project_name}}`. Support is provided on a best-effort basis by the open-source community and maintainers.
diff --git a/docker-compose.yml b/docker-compose.yml
new file mode 100644
index 0000000..da6a338
--- /dev/null
+++ b/docker-compose.yml
@@ -0,0 +1,38 @@
+# ---------------------------------------------------------
+# {{project_name}} Docker Compose
+# Licensed under the Apache License, Version 2.0
+# ---------------------------------------------------------
+
+services:
+ app:
+ build:
+ context: .
+ target: builder
+ ports:
+ - "${APP_PORT:-8080}:8080"
+ volumes:
+ - ./src:/app/src
+ environment:
+ - APP_ENV=${APP_ENV:-development}
+ - APP_DEBUG=${APP_DEBUG:-true}
+ # Replace this with your language-specific live-reload or run command
+ # Examples: ["npm", "run", "dev"], ["make", "run"], ["cargo", "run"]
+ command: ["/bin/sh", "-c", "echo 'Please define a command in docker-compose.yml!'; exit 1"]
+
+ # Standard Database Profile
+ # Use `docker-compose --profile db up` to start this service
+ db:
+ image: postgres:15-alpine
+ profiles:
+ - db
+ ports:
+ - "5432:5432"
+ environment:
+ POSTGRES_USER: ${DB_USER:-admin}
+ POSTGRES_PASSWORD: ${DB_PASSWORD:-secret}
+ POSTGRES_DB: ${DB_NAME:-{{project_name}}_dev}
+ volumes:
+ - db_data:/var/lib/postgresql/data
+
+volumes:
+ db_data:
diff --git a/docs/README.md b/docs/README.md
new file mode 100644
index 0000000..68d078c
--- /dev/null
+++ b/docs/README.md
@@ -0,0 +1,172 @@
+# Documentation
+
+This directory contains the source files for the `{{project_name}}` documentation site, built with [MkDocs](https://www.mkdocs.org/) and the [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/) theme.
+
+## Directory Structure
+
+```
+docs/
+├── assets/ # Branding assets (logos, diagrams, favicons)
+├── community/ # Contributing, Code of Conduct, Security, Support
+├── examples/ # Runnable code examples and demos
+├── getting-started/ # Installation, quick start, and workflow guides
+├── guides/ # Task-oriented how-to guides
+├── reference/ # API reference and configuration schema
+├── scripts/ # Custom JavaScript for the docs site (extra.js)
+├── stylesheets/ # Custom CSS for the docs site (extra.css)
+├── index.md # Docs home page (hero landing page)
+└── README.md # This file
+```
+
+The MkDocs configuration lives at the repository root: [`mkdocs.yml`](../mkdocs.yml).
+
+
+## Prerequisites
+
+- **Python 3.9+** — Required to run MkDocs and its plugins.
+- **pip** — For installing documentation dependencies.
+
+All documentation dependencies are listed in `docs/requirements.txt`. Install them with:
+
+```bash
+pip install -r docs/requirements.txt
+```
+
+> **Tip:** See [DEVELOPING.md](../DEVELOPING.md) for the full local setup guide. Even if your main project is not in Python, the documentation is built with MkDocs and requires a Python environment to build locally.
+
+
+
+## Local Development
+
+### Serve the Docs Locally
+
+Start the live-reloading development server from the **repository root**:
+
+```bash
+mkdocs serve
+```
+
+The site will be available at [http://127.0.0.1:8000](http://127.0.0.1:8000). Any change you save to a source file is reflected immediately in the browser — no manual refresh needed.
+
+### Specify a Custom Host or Port
+
+```bash
+mkdocs serve --dev-addr 0.0.0.0:8080
+```
+
+### Template Variables
+
+All `{{ variable }}` references in the docs (e.g. `{{ project_name }}`, `{{ org_name }}`) are driven by the `extra:` block in [`mkdocs.yml`](../mkdocs.yml). Update those values once and the change propagates across the entire site:
+
+```yaml
+# mkdocs.yml
+extra:
+ project_name: "my-project"
+ org_name: "my-org"
+ # ... other variables
+```
+
+
+## Building the Docs
+
+Produce a static build of the site in the `site/` directory:
+
+```bash
+mkdocs build
+```
+
+> The `site/` directory is intentionally excluded from version control via `.gitignore`. Do **not** commit it manually.
+
+To perform a clean build (removes the previous `site/` output first):
+
+```bash
+mkdocs build --clean
+```
+
+Validate that all internal links resolve correctly:
+
+```bash
+mkdocs build --strict
+```
+
+The `--strict` flag is recommended before opening a pull request or cutting a release to catch broken links early.
+
+
+## Publishing the Docs
+
+### Automated Publishing (Recommended)
+
+Documentation is published automatically to **GitHub Pages** on every merge to `main` (or on a tagged release, depending on your workflow configuration). No manual steps are required — simply merge your changes and the CI/CD pipeline handles the rest.
+
+See the relevant workflow file in [`.github/workflows/`](../.github/workflows/) for the exact trigger and deployment steps.
+
+### Manual Publishing
+
+If you need to publish outside of the normal CI/CD cycle, run the following from the **repository root**:
+
+```bash
+mkdocs gh-deploy --force
+```
+
+This command builds the static site and force-pushes it to the `gh-pages` branch of your repository, which GitHub Pages then serves automatically.
+
+> **Note:** Manual deploys require you to have write access to the repository and a configured `git` identity (`user.name` and `user.email`).
+
+#### Dry-run First
+
+To preview what `gh-deploy` would do without actually pushing:
+
+```bash
+mkdocs gh-deploy --dry-run
+```
+
+
+## Adding and Editing Pages
+
+1. **Create a new `.md` file** in the appropriate subdirectory (e.g., `guides/my-new-guide.md`).
+2. **Register it in the nav** by adding an entry to the `nav:` block in [`mkdocs.yml`](../mkdocs.yml).
+3. **Preview locally** with `mkdocs serve` before opening a pull request.
+
+### Page Metadata
+
+Every page should include a top-level `# Heading` that matches its nav label. Optionally, add MkDocs front matter for advanced layout control:
+
+```yaml
+---
+hide:
+ - toc # Hide the table of contents
+ - navigation # Hide the left-hand nav
+---
+```
+
+### Admonitions
+
+This site uses [PyMdown Extensions](https://facelessuser.github.io/pymdown-extensions/) and MkDocs Material admonitions. Use them liberally:
+
+```markdown
+!!! note
+ This is an informational note.
+
+!!! warning
+ This is a warning.
+```
+
+
+## Common Troubleshooting
+
+| Symptom | Likely Cause | Fix |
+| :--- | :--- | :--- |
+| `mkdocs: command not found` | Dependencies not installed | `pip install mkdocs mkdocs-material mkdocs-macros-plugin pymdown-extensions` |
+| `{{ variable }}` renders literally | `mkdocs-macros-plugin` missing or misconfigured | Confirm `macros` is listed under `plugins:` in `mkdocs.yml` |
+| Broken links on `--strict` build | Missing or misnamed file in `nav:` | Verify file path and `nav:` registration in `mkdocs.yml` |
+| Styles missing in local preview | Custom CSS path wrong | Confirm `extra_css` path in `mkdocs.yml` matches `docs/stylesheets/extra.css` |
+| `gh-deploy` push rejected | Stale `gh-pages` branch | Use `mkdocs gh-deploy --force` or delete and re-create the `gh-pages` branch |
+
+
+## Related Resources
+
+- [MkDocs Documentation](https://www.mkdocs.org/)
+- [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/)
+- [MkDocs Macros Plugin](https://mkdocs-macros-plugin.readthedocs.io/)
+- [PyMdown Extensions](https://facelessuser.github.io/pymdown-extensions/)
+- [GitHub Pages — Publishing Source](https://docs.github.com/en/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site)
diff --git a/docs/assets/branding/logo-dark.svg b/docs/assets/branding/logo-dark.svg
new file mode 100644
index 0000000..aa65525
--- /dev/null
+++ b/docs/assets/branding/logo-dark.svg
@@ -0,0 +1,4 @@
+
diff --git a/docs/assets/branding/logo-light.svg b/docs/assets/branding/logo-light.svg
new file mode 100644
index 0000000..20e3af2
--- /dev/null
+++ b/docs/assets/branding/logo-light.svg
@@ -0,0 +1,4 @@
+
diff --git a/docs/assets/branding/user-flow-dark.svg b/docs/assets/branding/user-flow-dark.svg
new file mode 100644
index 0000000..eb05e1c
--- /dev/null
+++ b/docs/assets/branding/user-flow-dark.svg
@@ -0,0 +1,5 @@
+
diff --git a/docs/assets/branding/user-flow-light.svg b/docs/assets/branding/user-flow-light.svg
new file mode 100644
index 0000000..d3c0ad3
--- /dev/null
+++ b/docs/assets/branding/user-flow-light.svg
@@ -0,0 +1,5 @@
+
diff --git a/docs/community/agents.md b/docs/community/agents.md
new file mode 100644
index 0000000..97ecbc2
--- /dev/null
+++ b/docs/community/agents.md
@@ -0,0 +1 @@
+--8<-- "AGENTS.md"
diff --git a/docs/community/code-of-conduct.md b/docs/community/code-of-conduct.md
new file mode 100644
index 0000000..01f2ea2
--- /dev/null
+++ b/docs/community/code-of-conduct.md
@@ -0,0 +1 @@
+--8<-- "CODE_OF_CONDUCT.md"
diff --git a/docs/community/contributing.md b/docs/community/contributing.md
new file mode 100644
index 0000000..ea38c9b
--- /dev/null
+++ b/docs/community/contributing.md
@@ -0,0 +1 @@
+--8<-- "CONTRIBUTING.md"
diff --git a/docs/community/developing.md b/docs/community/developing.md
new file mode 100644
index 0000000..6e6ec19
--- /dev/null
+++ b/docs/community/developing.md
@@ -0,0 +1 @@
+--8<-- "DEVELOPING.md"
diff --git a/docs/community/index.md b/docs/community/index.md
new file mode 100644
index 0000000..7f3e639
--- /dev/null
+++ b/docs/community/index.md
@@ -0,0 +1,61 @@
+# Community
+
+`{{ project_name }}` is an open-source project and we welcome participation from everyone. This section contains all the resources you need to get involved, stay informed, and interact with the community.
+
+
+## Get Involved
+
+
+
+- :material-source-pull: **Contributing**
+
+ ---
+
+ How to report bugs, suggest features, and submit pull requests.
+
+ [:octicons-arrow-right-24: Contributing Guide](contributing.md)
+
+- :material-wrench-outline: **Developer Setup**
+
+ ---
+
+ Full environment setup guide for contributors — Docker, local dev,
+ testing, and code quality standards.
+
+ [:octicons-arrow-right-24: Developer Setup](developing.md)
+
+- :material-handshake-outline: **Code of Conduct**
+
+ ---
+
+ Our community standards and the guidelines we expect all participants to follow.
+
+ [:octicons-arrow-right-24: Code of Conduct](code-of-conduct.md)
+
+- :material-shield-lock-outline: **Security Policy**
+
+ ---
+
+ How to responsibly disclose security vulnerabilities and our triage process.
+
+ [:octicons-arrow-right-24: Security Policy](security.md)
+
+- :material-lifebuoy: **Support**
+
+ ---
+
+ Where to ask questions, report issues, and find help.
+
+ [:octicons-arrow-right-24: Support](support.md)
+
+
+
+
+## Community Channels
+
+| Channel | Purpose |
+| :--- | :--- |
+| [GitHub Issues](https://github.com/{{ org_name }}/{{ project_name }}/issues) | Bug reports and feature requests |
+| [GitHub Discussions](https://github.com/{{ org_name }}/{{ project_name }}/discussions) | Q&A, ideas, and general community conversation |
+| [Slack]({{ slack_url }}) | Real-time chat with the team and community |
+| [Blog]({{ blog_url }}) | Project updates, tutorials, and announcements |
diff --git a/docs/community/security.md b/docs/community/security.md
new file mode 100644
index 0000000..a8ada70
--- /dev/null
+++ b/docs/community/security.md
@@ -0,0 +1 @@
+--8<-- "SECURITY.md"
diff --git a/docs/community/support.md b/docs/community/support.md
new file mode 100644
index 0000000..05fc079
--- /dev/null
+++ b/docs/community/support.md
@@ -0,0 +1 @@
+--8<-- "SUPPORT.md"
diff --git a/docs/examples/index.md b/docs/examples/index.md
new file mode 100644
index 0000000..9bcbff5
--- /dev/null
+++ b/docs/examples/index.md
@@ -0,0 +1,53 @@
+# Examples
+
+This section contains runnable code examples that demonstrate real-world usage of `{{ project_name }}`. Each example is self-contained and can be copied directly into your own project.
+
+> [!NOTE]
+> All examples assume you have completed [Installation](../getting-started/installation.md). Replace `YOUR_KEY` and other placeholder values with your own credentials before running.
+
+
+## Example Categories
+
+
+
+- :material-rocket-launch-outline: **Basic Examples**
+
+ ---
+
+ Simple, minimal examples that demonstrate the core API with no extra setup required. The best place to start.
+
+
+ *Coming soon.*
+
+- :material-tune-variant: **Advanced Examples**
+
+ ---
+
+ Examples that demonstrate more complex patterns, custom configurations, and production-grade usage.
+
+
+ *Coming soon.*
+
+- :material-console: **CLI Examples**
+
+ ---
+
+ Examples using the `{{ project_name }}` command-line interface, including scripting and automation patterns.
+
+
+ *Coming soon.*
+
+- :material-docker: **Docker Examples**
+
+ ---
+
+ Containerised usage examples, including Docker Compose configurations for common deployment scenarios.
+
+
+ *Coming soon.*
+
+
+
+
+!!! tip "Contributing an Example"
+ Have a useful snippet or pattern to share? See the [Contributing Guide](../community/contributing.md) to learn how to add a new example to this section.
diff --git a/docs/getting-started/index.md b/docs/getting-started/index.md
new file mode 100644
index 0000000..045d997
--- /dev/null
+++ b/docs/getting-started/index.md
@@ -0,0 +1,38 @@
+# Getting Started
+
+Welcome to `{{ project_name }}`! This section walks you through everything you need to go from zero to productive.
+
+Follow the pages in order for the best experience, or jump directly to the section you need.
+
+
+## In This Section
+
+
+
+- :material-download-outline: **Installation**
+
+ ---
+
+ Install `{{ project_name }}` via pip, from source, or using Docker.
+ Includes platform-specific notes and verification steps.
+
+ [:octicons-arrow-right-24: Installation Guide](installation.md)
+
+- :material-play-circle-outline: **Quick Start**
+
+ ---
+
+ Your first 5 minutes with `{{ project_name }}`. Initialize, run a command,
+ and see results — fast.
+
+ [:octicons-arrow-right-24: Quick Start](quickstart.md)
+
+- :material-transit-connection-variant: **Workflows**
+
+ ---
+
+ End-to-end walkthroughs for the most common user stories and usage patterns.
+
+ [:octicons-arrow-right-24: Workflows](workflows.md)
+
+
diff --git a/docs/getting-started/installation.md b/docs/getting-started/installation.md
new file mode 100644
index 0000000..22dcac3
--- /dev/null
+++ b/docs/getting-started/installation.md
@@ -0,0 +1,116 @@
+# Installation
+
+This page covers all supported installation methods for `{{ project_name }}`.
+
+
+## Requirements
+
+Before installing, ensure your system meets the following prerequisites:
+
+| Requirement | Minimum Version | Notes |
+| :--- | :--- | :--- |
+| **Language** | | Required for all installation methods |
+| **Package Manager**| | Required for dependencies |
+| **Git** | 2.x | Required for source installs |
+| **Docker** | 24.x | Optional — for containerized installs |
+
+
+## Standard Installation
+
+The recommended way to install `{{ project_name }}` for most users:
+
+```bash
+
+# e.g., npm install {{project_name}} OR pip install {{project_name}} OR cargo add {{project_name}}
+```
+
+### Verify the Installation
+
+After installation, confirm it is working correctly:
+
+```bash
+{{ project_name }} --version
+```
+
+You should see output similar to:
+
+```console
+{{ project_name }} 0.1.0
+```
+
+
+## Install from Source
+
+To install the latest unreleased code directly from the repository:
+
+```bash
+git clone https://github.com/{{ org_name }}/{{ project_name }}.git
+cd {{ project_name }}
+
+# Install dependencies for development
+
+# e.g., npm ci OR pip install -e ".[dev]" OR cargo build
+```
+
+> [!TIP]
+> This is the recommended setup for contributors looking to make changes to the source code.
+
+
+## Docker Installation
+
+A pre-built Docker image is available for containerized environments:
+
+```bash
+# Pull the latest image
+docker pull ghcr.io/{{ org_name }}/{{ project_name }}:latest
+
+# Run a one-off command
+docker run --rm ghcr.io/{{ org_name }}/{{ project_name }}:latest {{ project_name }} --version
+```
+
+For a persistent, volume-mounted setup using Docker Compose, see the `docker-compose.yml` in the root of the repository.
+
+
+## Platform-Specific Notes
+
+=== "macOS"
+
+
+
+=== "Linux"
+
+
+
+=== "Windows"
+
+
+
+
+## Upgrading
+
+To upgrade an existing installation to the latest release:
+
+```bash
+
+```
+
+
+## Uninstalling
+
+```bash
+
+```
+
+
+## Troubleshooting
+
+| Problem | Solution |
+| :--- | :--- |
+| `command not found: {{ project_name }}` | Ensure the binaries directory is on your `$PATH`. |
+| Import errors after install | Ensure you have the latest version installed. |
+| Version conflicts | Isolate your dependencies using your language's recommended tool. |
+
+If you continue to experience issues, please visit our [Support page](../community/support.md).
+
+
+**Next:** [Quick Start →](quickstart.md)
diff --git a/docs/getting-started/quickstart.md b/docs/getting-started/quickstart.md
new file mode 100644
index 0000000..490f2ce
--- /dev/null
+++ b/docs/getting-started/quickstart.md
@@ -0,0 +1,68 @@
+# Quick Start
+
+This guide gets you from a fresh installation to running your first command in under 5 minutes.
+
+> [!NOTE]
+> Make sure you have completed [Installation](installation.md) before continuing.
+
+
+## Step 1 — Initialize Your Environment
+
+If you haven't already, set up your project and install `{{ project_name }}`:
+
+```bash
+
+# e.g., npm init && npm install {{project_name}}
+```
+
+
+## Step 2 — Verify the Install
+
+```bash
+{{ project_name }} --version
+```
+
+Expected output:
+
+```console
+{{ project_name }} 0.1.0
+```
+
+
+## Step 3 — Run Your First Command
+
+```text
+
+// e.g., Javascript, Python, Go, Rust
+import { Client } from '{{ project_name }}';
+
+// Initialize the client
+const client = new Client({ apiKey: "YOUR_KEY" });
+
+// Run a core action
+const result = await client.runAction("hello_world");
+console.log(result);
+```
+
+Expected output:
+
+```console
+[INFO] Initializing {{ project_name }} client...
+[SUCCESS] Action completed! Result: Hello, World from {{ project_name }}!
+```
+
+> [!TIP]
+> Replace `"YOUR_KEY"` with your actual API key or credentials. See the [Reference](../reference/index.md) for all available client configuration options.
+
+
+## Step 4 — Explore Further
+
+Now that your first command works, explore what `{{ project_name }}` can do:
+
+- **[Workflows](workflows.md)** — Common end-to-end usage patterns
+- **[Guides](../guides/index.md)** — Task-specific deep dives
+- **[Reference](../reference/index.md)** — Full API and CLI documentation
+- **[Examples](../examples/index.md)** — Runnable code examples
+
+
+**Next:** [Workflows →](workflows.md)
diff --git a/docs/getting-started/workflows.md b/docs/getting-started/workflows.md
new file mode 100644
index 0000000..9fd3c41
--- /dev/null
+++ b/docs/getting-started/workflows.md
@@ -0,0 +1,99 @@
+# Workflows
+
+This page walks through the most common end-to-end usage patterns for `{{ project_name }}`. Each workflow is a self-contained user story — pick the one that matches your use case.
+
+> [!NOTE]
+> These are placeholder workflows. Replace each section with the real workflows that users of your project will follow.
+
+
+## Workflow 1 — Basic Usage
+
+**Goal:** Perform the most common, standard operation with `{{ project_name }}`.
+
+### Steps
+
+1. **Initialize the client**
+
+ ```text
+
+ ```
+
+2. **Configure your inputs**
+
+ ```text
+
+ ```
+
+3. **Execute the action**
+
+ ```text
+
+ ```
+
+4. **Handle the output**
+
+ ```text
+
+ ```
+
+
+## Workflow 2 — Docker-Based Execution
+
+**Goal:** Run `{{ project_name }}` in a containerized environment without any local setup.
+
+### Steps
+
+1. **Pull the image**
+
+ ```bash
+ docker pull ghcr.io/{{ org_name }}/{{ project_name }}:latest
+ ```
+
+2. **Run with environment variables**
+
+ ```bash
+ docker run --rm \
+ -e API_KEY="YOUR_KEY" \
+ -v $(pwd)/output:/app/output \
+ ghcr.io/{{ org_name }}/{{ project_name }}:latest \
+ {{ project_name }} run --output /app/output
+ ```
+
+3. **Inspect the output**
+
+ ```bash
+ ls ./output/
+ ```
+
+
+## Workflow 3 — CI/CD Integration
+
+**Goal:** Integrate `{{ project_name }}` into a GitHub Actions pipeline.
+
+```yaml
+# .github/workflows/run.yml
+name: Run {{ project_name }}
+
+on: [push]
+
+jobs:
+ run:
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@v4
+
+ - name: Set up environment
+ #
+
+ - name: Install {{ project_name }}
+ run: |
+ #
+
+ - name: Run action
+ env:
+ API_KEY: ${{ "{{" }} secrets.API_KEY {{ "}}" }}
+ run: {{ project_name }} run --config config.yaml
+```
+
+
+**Need more?** See the [Guides](../guides/index.md) section for in-depth task-specific documentation or browse the [Examples](../examples/index.md) for runnable code.
diff --git a/docs/guides/index.md b/docs/guides/index.md
new file mode 100644
index 0000000..a891c37
--- /dev/null
+++ b/docs/guides/index.md
@@ -0,0 +1,50 @@
+# Guides
+
+This section contains task-oriented how-to guides for `{{ project_name }}`. Unlike the [Getting Started](../getting-started/index.md) section, which is structured as a linear onboarding path, these guides are standalone — jump to whichever one is relevant to your current task.
+
+
+## Available Guides
+
+
+
+- :material-cog-outline: **Configuration**
+
+ ---
+
+ A deep dive into all configuration options, file formats, and environment variables supported by `{{ project_name }}`.
+
+
+ *Coming soon.*
+
+- :material-puzzle-outline: **Integrations**
+
+ ---
+
+ Step-by-step instructions for integrating `{{ project_name }}` with third-party tools, platforms, and services.
+
+
+ *Coming soon.*
+
+- :material-shield-half-full: **Authentication & Security**
+
+ ---
+
+ How to configure authentication, manage secrets, and follow security best practices when deploying `{{ project_name }}`.
+
+
+ *Coming soon.*
+
+- :material-swap-horizontal: **Migration**
+
+ ---
+
+ Guides for upgrading between major versions and migrating from other tools to `{{ project_name }}`.
+
+
+ *Coming soon.*
+
+
+
+
+!!! tip "Contributing a Guide"
+ Have a workflow or pattern worth documenting? See the [Contributing Guide](../community/contributing.md) to learn how to add a new guide to this section.
diff --git a/docs/index.md b/docs/index.md
new file mode 100644
index 0000000..8f5f5ef
--- /dev/null
+++ b/docs/index.md
@@ -0,0 +1,93 @@
+---
+hide:
+ - navigation
+ - toc
+---
+
+
+
+
+# {{ project_name }}
+
+**{{ project_description }}**
+
+A production-ready Apache 2.0 template that gives you a fully structured, documented, and CI/CD-enabled starting point — so you can focus on building, not scaffolding.
+
+[Get Started](getting-started/index.md){ .md-button .md-button--primary }
+[View on GitHub](https://github.com/{{ org_name }}/{{ project_name }}){ .md-button }
+
+
+
+
+
+## What's Included
+
+
+
+- :material-rocket-launch-outline: **Getting Started**
+
+ ---
+
+ Installation guide, quick start tutorial, and common workflow walkthroughs.
+
+ [:octicons-arrow-right-24: Get Started](getting-started/index.md)
+
+- :material-book-open-outline: **Guides**
+
+ ---
+
+ Step-by-step guides for common tasks, integrations, and configuration patterns.
+
+ [:octicons-arrow-right-24: Browse Guides](guides/index.md)
+
+- :material-code-braces: **Examples**
+
+ ---
+
+ Runnable code examples that demonstrate real-world usage of `{{ project_name }}`.
+
+ [:octicons-arrow-right-24: See Examples](examples/index.md)
+
+- :material-file-document-outline: **Reference**
+
+ ---
+
+ Full API reference, CLI documentation, and configuration schema.
+
+ [:octicons-arrow-right-24: View Reference](reference/index.md)
+
+- :material-account-group-outline: **Community**
+
+ ---
+
+ Contributing guide, developer setup, Code of Conduct, and support resources.
+
+ [:octicons-arrow-right-24: Get Involved](community/index.md)
+
+- :material-shield-lock-outline: **Security**
+
+ ---
+
+ Our security policy, responsible disclosure process, and supported versions.
+
+ [:octicons-arrow-right-24: Security Policy](community/security.md)
+
+
+
+
+## Quick Install
+
+```bash
+
+# e.g., npm install {{project_name}} OR pip install {{project_name}}
+```
+
+For advanced installation options (from source, Docker, etc.) see the [Installation Guide](getting-started/installation.md).
+
+
+## Links
+
+- :material-github: [GitHub Repository](https://github.com/{{ org_name }}/{{ project_name }})
+- :material-map-marker-path: [Roadmap]({{ roadmap_url }})
+- :material-post-outline: [Blog]({{ blog_url }})
+- :material-slack: [Slack Community]({{ slack_url }})
diff --git a/docs/reference/index.md b/docs/reference/index.md
new file mode 100644
index 0000000..4720b0c
--- /dev/null
+++ b/docs/reference/index.md
@@ -0,0 +1,71 @@
+# Reference
+
+The Reference section contains the complete technical documentation for `{{ project_name }}` — API classes, CLI commands, and configuration options. This is the section to bookmark when you need to look something up.
+
+
+## In This Section
+
+
+
+- :material-code-json: **API Reference**
+
+ ---
+
+ Auto-generated documentation for all public classes, methods, and modules.
+
+
+ *Coming soon — see [Contributing](../community/contributing.md) to help.*
+
+- :material-console: **CLI Reference**
+
+ ---
+
+ Full documentation for all `{{ project_name }}` command-line interface commands,
+ options, and flags.
+
+
+ *Coming soon.*
+
+- :material-tune-variant: **Configuration Schema**
+
+ ---
+
+ All supported configuration file options, types, defaults, and examples.
+
+
+ *Coming soon.*
+
+
+
+
+## Generating API Reference Docs
+
+This template is pre-configured to work with [`mkdocstrings`](https://mkdocstrings.github.io/) for auto-generating API documentation from docstrings.
+
+### Setup
+
+> [!NOTE]
+> `mkdocstrings` supports multiple languages via handlers (e.g., Python, C++, Crystal). See the [mkdocstrings documentation](https://mkdocstrings.github.io/) to configure it for your language.
+
+1. Install the plugin and your language handler (e.g., for Python):
+
+ ```bash
+ pip install mkdocstrings[python]
+ ```
+
+2. Configure `mkdocs.yml` according to your language handler and create your reference pages.
+
+
+## Generating CLI Reference Docs
+
+For CLI documentation, consider using one of the following approaches depending on your CLI framework:
+
+| Framework | Plugin | Notes |
+| :--- | :--- | :--- |
+| **Typer** | [`typer-cli`](https://typer.tiangolo.com/typer-cli/) | Generates markdown from Typer apps |
+| **Click** | [`mkdocs-click`](https://github.com/brunoliveira8/mkdocs-click) | Auto-generates docs from Click decorators |
+| **Argparse** | Manual | Document commands in a dedicated `cli.md` page |
+
+
+!!! tip "Template Reminder"
+ Replace this page with actual generated reference documentation as your project matures. The placeholders above are intentional starting points.
diff --git a/docs/requirements.txt b/docs/requirements.txt
new file mode 100644
index 0000000..2b17cec
--- /dev/null
+++ b/docs/requirements.txt
@@ -0,0 +1,4 @@
+mkdocs>=1.6.0
+mkdocs-material>=9.5.0
+mkdocs-macros-plugin>=1.0.0
+pymdown-extensions>=10.7
diff --git a/docs/scripts/extra.js b/docs/scripts/extra.js
new file mode 100644
index 0000000..5011454
--- /dev/null
+++ b/docs/scripts/extra.js
@@ -0,0 +1 @@
+/* Custom JavaScript for MkDocs */
diff --git a/docs/stylesheets/extra.css b/docs/stylesheets/extra.css
new file mode 100644
index 0000000..1bb13e7
--- /dev/null
+++ b/docs/stylesheets/extra.css
@@ -0,0 +1 @@
+/* Custom Stylesheet for MkDocs */
diff --git a/examples/README.md b/examples/README.md
new file mode 100644
index 0000000..d3b387f
--- /dev/null
+++ b/examples/README.md
@@ -0,0 +1,51 @@
+# {{project_name}} Examples
+
+This directory contains practical, runnable demonstrations of how to use `{{project_name}}` in various scenarios. These examples are designed to help you quickly understand core concepts, advanced configurations, and best practices.
+
+
+## Prerequisites
+
+Before running the examples, ensure you have set up your environment correctly:
+
+1. **Install Dependencies:** Make sure you have installed the core package for your environment and any example-specific requirements.
+2. **Environment Variables:** Copy `.env.example` to `.env` if the examples require configuration (e.g., API keys or external services).
+
+> [!NOTE]
+> Some examples may require additional dependencies not included in the core `{{project_name}}` package. Please check the `README.md` within each specific example directory for details.
+
+
+## Example Index
+
+Below is a curated list of available examples, categorized by complexity:
+
+| Example | Complexity | Description |
+| :--- | :--- | :--- |
+| **`[example_name/](example_name/)`** | ⭐ Beginner / ⭐⭐⭐ Advanced | Briefly describe the example and what core concepts it demonstrates. |
+
+
+
+
+## Running the Examples
+
+Most examples can be executed directly from the command line. Navigate to the root of the repository and run the desired script:
+
+```bash
+# Example: Running a generic example script
+
+# e.g., node examples/example_name/main.js OR python examples/example_name/main.py
+```
+
+> [!TIP]
+> **Always run examples from the repository root.** This ensures that all relative paths, environment variables, and module imports resolve correctly.
+
+
+## Contributing New Examples
+
+We welcome community contributions! If you have a use case that isn't covered, please consider submitting a new example:
+
+1. Create a new directory under `examples/` with a descriptive name.
+2. Include a focused, easily digestible script or application.
+3. Add a local `README.md` within your example directory explaining what it does and how to run it.
+4. Update the **Example Index** table above.
+
+For more details on contributing, please review our [Contributing Guide](../CONTRIBUTING.md).
diff --git a/llms-full.txt b/llms-full.txt
new file mode 100644
index 0000000..879291d
--- /dev/null
+++ b/llms-full.txt
@@ -0,0 +1,575 @@
+# {{project_name}} Full Documentation
+
+This file contains the concatenated core documentation for the project to provide comprehensive context to LLMs.
+
+## File: README.md
+
+
+
+
+
+
+
+
+
+
+ An opinionated, production-ready Apache 2.0 template repository for bootstrapping modern software projects.
+
+
+Welcome to the {{project_name}} template repository! This template provides a robust foundation for building high-quality, scalable software projects. It includes standard directories, issue templates, CI/CD workflows, and comprehensive placeholder documentation.
+
+To use this template, simply find and replace all instances of `{{project_name}}` and `{{organization}}` with your actual project details, update the placeholder SVG images in `docs/assets/branding/`, and you are ready to start coding.
+
+### Why Use {{project_name}}?
+
+- **Consistency:** Enforces a standardized layout and structure across your organization's repositories.
+- **Speed:** Bootstraps your project with pre-configured Actions, badges, and templates so you don't start from scratch.
+- **Best Practices:** Baked-in guides for contributing, security, and developer setup.
+
+### Comparisons
+
+When evaluating {{project_name}} against other templates, consider the following differences:
+
+| Feature | {{project_name}} Template | Standard GitHub Init | Cookiecutter / Copier |
+| :--- | :--- | :--- | :--- |
+| **Setup Speed** | Very Fast | Fast | Slower (requires CLI tool) |
+| **Visual Assets** | Pre-configured Light/Dark assets | None | Varies |
+| **CI/CD Built-in** | Yes (GitHub Actions) | No | Optional |
+| **Complexity** | Low (Find and Replace) | None | Medium (Jinja templates) |
+
+
+## What's New
+
+**Welcome to the {{project_name}} Launch!**
+
+This project has just been instantiated from the template repository. Keep an eye on this section for future release highlights, new features, and community announcements!
+
+
+
+## Quick Start
+
+```bash
+pip install {{project_name}}
+```
+
+For full installation options (from source, Docker, platform-specific notes) and step-by-step onboarding, see the **[Getting Started guide](https://{{organization}}.github.io/{{project_name}}/getting-started/)**.
+
+## Core Concepts
+
+
+
+### Component Architecture
+
+The template is organized into several key areas:
+- `docs/`: Stores your documentation and branding assets.
+- `src/` (or your primary package directory): The core application logic.
+- `tests/`: Automated tests to ensure code quality.
+
+## Advanced Usage
+
+
+
+## General
+
+### Contributing
+
+We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for more details. For development setup, check out [DEVELOPING.md](DEVELOPING.md).
+Please ensure you follow our [Code of Conduct](CODE_OF_CONDUCT.md) in all interactions.
+
+### Support and Security
+
+- For help and general questions, see [SUPPORT.md](SUPPORT.md).
+- To report a security vulnerability, please refer to our [Security Policy](SECURITY.md).
+
+### AI & LLM Tooling
+
+This repository includes first-class support for agentic and LLM-assisted development workflows:
+
+- **[AGENTS.md](AGENTS.md):** Repository-specific instructions for AI coding agents (Codex, Copilot Workspace, Gemini, Claude, Cursor, and similar tools). Contains the authoritative guide for project structure, executable commands, code style, and critical constraints.
+- **[llms.txt](llms.txt):** A machine-readable index of the project's documentation, following the [llms.txt specification](https://llmstxt.org/). Served at `/llms.txt` on the documentation site to help LLMs quickly locate and consume relevant content.
+
+### License
+
+This project is licensed under the Apache License 2.0. See the [LICENSE](LICENSE) file for details.
+
+### Citations
+
+If you use this template or the resulting software in your research, please cite it using the following BibTeX entry:
+
+```bibtex
+@software{{{project_name}},
+ author = {{{organization}}},
+ title = {{{project_name}}},
+ version = {{{version}}},
+ month = {{{month}}},
+ year = {2026},
+ url = {https://github.com/{{organization}}/{{project_name}}}
+}
+```
+
+## File: AGENTS.md
+
+# AGENTS.md — AI Agent & Coding Assistant Guide
+
+> **This file provides repository-specific instructions to AI coding agents** (e.g., OpenAI Codex, GitHub Copilot, Gemini, Claude, Cursor).
+> Human contributors should refer to [DEVELOPING.md](DEVELOPING.md).
+
+## Project Context
+
+**`{{project_name}}`** is a production-ready Apache 2.0 template repository for bootstrapping modern software projects.
+**Primary language:** ``
+**Package manager:** ``
+
+## Critical Constraints
+
+> [!CAUTION]
+> 1. **Never commit secrets.** Do not add API keys, tokens, or credentials anywhere.
+> 2. **Do not modify `LICENSE` or `NOTICE`.** These are legally binding.
+> 3. **Do not modify workflow trigger conditions** without human review.
+> 4. **All new source files must include the Apache 2.0 copyright header.**
+> 5. **Use `{{double_braces}}` for template placeholders.** Never hard-code them.
+
+## Repository Layout
+
+- `.github/workflows/`: CI/CD pipelines. Files prefixed with `_` are reusable templates.
+- `docs/`: MkDocs Material source.
+- `src/`: Primary application source code.
+- `tests/`: Organized into `unit/`, `integration/`, and `e2e/`.
+
+## Executable Commands
+
+- **Linting:** `pre-commit run --all-files`
+- **Testing:** ``
+- **Docs:** `mkdocs serve` / `mkdocs build`
+- **Build:** ``
+
+## Code Style & Patterns
+
+- **No magic strings or numbers** — define constants.
+- **Prefer explicit over implicit.**
+- **One responsibility per module.**
+- Every public function, class, and module must have a docstring.
+- Follow [Conventional Commits](https://www.conventionalcommits.org/).
+
+## GitHub Actions Workflows
+
+- **Reusable Templates (`_*.yml`):** Never trigger directly. Ensure changes are backward-compatible.
+- **Lifecycle:**
+ - `development.yml`: PR open/sync (unit + smoke)
+ - `main.yml`: Push to `main` (unit + integration + sanity)
+ - `nightly.yml`, `weekly.yml`, `release.yml`: Standard scheduled/release flows.
+
+## Documentation
+
+- **`docs/`** and **`mkdocs.yml`** control the site. Do not create docs outside the `nav:` tree.
+- `docs/index.md` dynamically includes `README.md` via MkDocs snippets.
+- Use `{{placeholder}}` variables for templated fields (e.g., `{{project_name}}`, `{{organization}}`).
+
+## Agent Notes
+
+_Add notes here when updating instructions for AI agents._
+
+## File: DEVELOPING.md
+
+# Developing `{{project_name}}`
+
+This guide provides instructions for setting up your development environment, navigating the project structure, and adhering to our coding standards.
+
+## Prerequisites
+
+Ensure your system meets the following requirements before getting started:
+
+- **[Docker](https://docs.docker.com/get-docker/)** (Recommended for isolated environments)
+- **[Git](https://git-scm.com/)** (Version control)
+-
+
+> [!NOTE]
+> We strongly recommend using our Docker setup to ensure your local environment exactly matches our CI/CD pipelines.
+
+## Quick Start (Docker)
+
+> [!IMPORTANT]
+> The `Dockerfile` and `docker-compose.yml` files included in this template are **placeholders** that must be filled in for your specific language stack before they are usable. The default `CMD` in both files will exit with an error if run without modification.
+>
+> Once implemented, you can spin up the development environment with:
+> ```bash
+> git clone https://github.com/{{organization}}/{{project_name}}.git
+> cd {{project_name}}
+>
+> # Build and start the development environment in the background
+> docker-compose up -d --build
+> ```
+
+To view the logs of your running containers:
+```bash
+docker-compose logs -f
+```
+
+## Local Setup
+
+If you prefer to develop directly on your host machine, follow the steps for your language stack.
+
+> [!NOTE]
+> **A note on shared tooling:** This project uses [pre-commit](https://pre-commit.com/) for git hooks (formatting, secret detection) and [MkDocs](https://www.mkdocs.org/) for documentation. Both require Python, regardless of your application's primary language. Install them once globally or in a dedicated virtual environment.
+>
+> ```bash
+> pip install pre-commit mkdocs-material
+> pre-commit install
+> ```
+
+### Python
+
+```bash
+# 1. Create and activate a virtual environment
+python -m venv .venv
+source .venv/bin/activate # Windows: .venv\Scripts\activate
+
+# 2. Install the package and development dependencies
+pip install -e ".[dev]"
+
+# 3. Install pre-commit hooks
+pre-commit install
+```
+
+### Node.js / TypeScript
+
+```bash
+# 1. Install all dependencies (uses lockfile for reproducibility)
+npm ci
+
+# 2. Install pre-commit hooks (requires Python; see note above)
+pre-commit install
+# Alternatively, use Husky for a pure Node.js hook solution:
+# npx husky install
+```
+
+### Go
+
+```bash
+# 1. Download module dependencies
+go mod download
+
+# 2. Install pre-commit hooks (requires Python; see note above)
+pre-commit install
+```
+
+### Rust
+
+```bash
+# 1. All dependencies are managed by Cargo automatically
+cargo build
+
+# 2. Install pre-commit hooks (requires Python; see note above)
+pre-commit install
+```
+
+## Running Tests
+
+We maintain strict testing standards. Our tests are located in the `tests/` directory and are categorized by tier.
+
+| Test Tier | Directory | Description |
+| :--- | :--- | :--- |
+| **Unit** | `tests/unit/` | Fast, isolated tests for individual functions and classes. |
+| **Integration** | `tests/integration/` | Slower tests that verify interactions between multiple components. |
+| **End-to-End** | `tests/e2e/` | Full-stack tests simulating real user workflows. |
+
+Replace the commands below with those appropriate for your language stack:
+
+```bash
+# Python (pytest)
+pytest tests/unit/
+pytest tests/integration/
+pytest tests/ # full suite with coverage
+pytest tests/ --cov=src --cov-report=xml
+
+# Node.js (Jest)
+npx jest tests/unit/
+npx jest --ci --coverage
+
+# Go
+go test ./tests/unit/...
+go test ./...
+
+# Rust
+cargo test --lib # unit tests
+cargo test --test '*' # integration tests
+```
+
+## Code Quality and Formatting
+
+We use opinionated formatters and linters to maintain consistency.
+
+- **Pre-commit Hooks:** The `.pre-commit-config.yaml` file in the repo root runs formatters and linters automatically before each commit. The hooks included by default are language-agnostic (whitespace, YAML validation, secret detection).
+- **Language-specific hooks:** Add your language's formatter/linter to `.pre-commit-config.yaml` (see the commented examples already present in the file).
+
+To run all hooks manually against the entire codebase:
+```bash
+pre-commit run --all-files
+```
+
+> [!TIP]
+> **IDE Configuration:** We highly recommend configuring your editor (e.g., VSCode, IntelliJ) to format on save using the project's formatting tools. For VSCode, ensure you have the relevant extensions installed and check `.vscode/settings.json` if available.
+
+## Git Workflow & Branching
+
+We follow a structured branching strategy to maintain a clean git history.
+
+1. **Branch Naming:**
+ - Feature branches: `feature/short-description`
+ - Bug fixes: `bugfix/short-description`
+ - Documentation: `docs/short-description`
+
+2. **Commit Messages:**
+ We encourage following [Conventional Commits](https://www.conventionalcommits.org/).
+ - `feat: add new user endpoint`
+ - `fix: resolve crash on startup`
+ - `docs: update developing guide`
+
+3. **Pull Requests:**
+ - Push your branch to the remote repository.
+ - Open a Pull Request against the `main` branch.
+ - Ensure all CI checks (tests, linters) pass.
+ - Request a review from at least one core maintainer.
+
+## Building Documentation
+
+Our documentation is built using [MkDocs Material](https://squidfunk.github.io/mkdocs-material/). To preview documentation changes locally:
+
+```bash
+# Install docs dependencies (if not already installed)
+pip install mkdocs-material
+
+# Serve documentation on http://127.0.0.1:8000 with hot-reload
+mkdocs serve
+```
+
+For further assistance, please refer to our [SUPPORT.md](SUPPORT.md).
+
+## File: CONTRIBUTING.md
+
+# Contributing to {{project_name}}
+
+First off, thank you for considering contributing to `{{project_name}}`! It's people like you that make this project great.
+
+## Code of Conduct
+
+By participating in this project, you are expected to uphold our [Code of Conduct](CODE_OF_CONDUCT.md). Please report any unacceptable behavior to the project team.
+
+## Security Vulnerabilities
+
+> [!IMPORTANT]
+> **Please do not report security vulnerabilities through public GitHub issues.**
+
+If you discover a security issue, please refer to our [Security Policy](SECURITY.md) for instructions on how to safely report it.
+
+## How Can I Contribute?
+
+There are many ways to contribute to `{{project_name}}`, and not all of them involve writing code:
+
+- **Reporting Bugs:** Help us improve by submitting detailed bug reports via our issue tracker.
+- **Suggesting Features:** Propose new features or enhancements that could benefit the project.
+- **Improving Documentation:** Fix typos, add examples, or write new guides.
+- **Writing Code:** Fix bugs, implement features, or improve performance.
+- **Helping Others:** Answer questions in [Discussions](https://github.com/{{organization}}/{{project_name}}/discussions) or issue comments.
+
+For general questions and help, please see [SUPPORT.md](SUPPORT.md).
+
+## Contributing Code
+
+If you are contributing code, please follow these structured steps:
+
+### 1. Development Setup
+
+Before you start coding, please refer to our [Development Guide](DEVELOPING.md) (`DEVELOPING.md`) for detailed instructions on:
+- Setting up your local environment
+- Installing dependencies
+- Running the test suite
+- Code formatting and linting standards
+
+### 2. Finding an Issue
+
+- Look for issues tagged with `good first issue` or `help wanted` if you are a new contributor.
+- If you plan to work on a major feature, please open an issue or discussion first to talk it over with the maintainers.
+
+### 3. Making Changes
+
+1. **Fork the Repository:** Fork the `{{project_name}}` repository to your GitHub account.
+2. **Create a Branch:** Create a new branch from `main` for your work (e.g., `git checkout -b feat/add-new-feature`).
+3. **Write Code:** Implement your changes, adhering to the project's coding standards.
+4. **Write Tests:** Add unit tests or integration tests for your changes to ensure stability.
+5. **Run Tests:** Ensure all tests and linters pass locally before committing.
+
+### 4. Committing Your Changes
+
+- Write clear, concise commit messages.
+- We recommend using [Conventional Commits](https://www.conventionalcommits.org/) (e.g., `feat: add support for X`, `fix: resolve issue with Y`).
+- If you are adding a new file, please include the appropriate Apache 2.0 copyright and license header at the top.
+
+### 5. Submitting a Pull Request
+
+1. **Push your branch:** `git push origin your-branch-name`.
+2. **Open a Pull Request:** Open a PR against the `main` branch of the upstream repository.
+3. **Fill out the PR Template:** Provide a clear description of your changes, link to any relevant issues (e.g., `Closes #123`), and complete any required checklists.
+4. **Pass CI:** Ensure all GitHub Actions CI checks pass.
+5. **Review:** Address any feedback from the maintainers. Once approved and checks pass, a maintainer will merge your PR.
+
+## Licensing
+
+By contributing to `{{project_name}}`, you agree that your contributions will be licensed under its [Apache 2.0 License](LICENSE).
+
+## File: SECURITY.md
+
+# Security Policy for `{{project_name}}`
+
+We take the security of `{{project_name}}` seriously. This document outlines our security policies, supported versions, and how to responsibly disclose a vulnerability.
+
+## Supported Versions
+
+Please check the table below for the versions of `{{project_name}}` that are currently being supported with security updates.
+
+| Version | Supported |
+| :--- | :--- |
+| `{{current_major_version}}.x` | :white_check_mark: |
+| `< {{current_major_version}}.0` | :x: |
+
+*(Note: Replace the table contents with your actual versioning scheme once released.)*
+
+## Reporting a Vulnerability
+
+> [!IMPORTANT]
+> **Please do not report security vulnerabilities through public GitHub issues, discussions, or pull requests.**
+
+If you discover a security vulnerability, please bring it to our attention right away using one of the following methods:
+
+1. **GitHub Security Advisories (Preferred):** Use the "Report a vulnerability" button on the **[Security tab](https://github.com/{{organization}}/{{project_name}}/security/advisories)** of this repository.
+2. **Email:** Send your report directly to **[INSERT EMAIL ADDRESS OR SECURITY CONTACT]**. *(Optional: Encrypt your email using our PGP key: [INSERT PGP KEY LINK/FINGERPRINT])*
+
+### What to Include in Your Report
+
+To help us resolve the issue quickly, please include the following information:
+- **Type of vulnerability** (e.g., XSS, SQLi, RCE, authorization bypass).
+- **Detailed description** of the vulnerability and its potential impact.
+- **Step-by-step instructions** to reproduce the issue.
+- **Proof of Concept (PoC)** code or screenshots, if available.
+- **Environment details** (e.g., version of `{{project_name}}`, OS, relevant configurations).
+
+## Triage and Resolution Process
+
+We will handle your report with strict confidentiality. Our process is as follows:
+
+1. **Acknowledgment:** We will respond to your report as soon as possible, usually within **[INSERT NUMBER, e.g., 48] hours**.
+2. **Triage:** We will investigate the issue and determine its validity and severity. We may contact you for further clarification.
+3. **Fix:** If the vulnerability is verified, we will develop and test a patch.
+4. **Disclosure:** We will coordinate with you to publicly disclose the vulnerability once a fix is released. We will publicly acknowledge your responsible disclosure, if you wish.
+
+## Scope
+
+**In Scope:**
+- Vulnerabilities within the core `{{project_name}}` codebase.
+- Security issues in our default configurations.
+
+**Out of Scope:**
+- Volumetric Denial of Service (DoS) attacks.
+- Theoretical issues without a reproducible PoC.
+- Vulnerabilities in third-party dependencies that are not exploitable through `{{project_name}}`.
+- Missing security headers or best practices that do not lead to a direct exploit.
+
+*(Note: We currently **[do/do not]** operate a bug bounty program. Disclosures are greatly appreciated but are not eligible for financial rewards at this time.)*
+
+## File: SUPPORT.md
+
+# Support for `{{project_name}}`
+
+We are excited to have you use `{{project_name}}`! If you need help, please follow these guidelines to ensure you get support quickly and efficiently.
+
+## Security Vulnerabilities
+
+> [!IMPORTANT]
+> **Please do not report security vulnerabilities through public GitHub issues.**
+
+If you have found a security vulnerability, please refer to our [Security Policy](SECURITY.md) for instructions on how to securely report it.
+
+## Where to Find Help
+
+Before reaching out, we recommend checking the following resources. Many common questions and issues are already covered there.
+
+- **[Official Documentation](https://{{organization}}.github.io/{{project_name}}):** Comprehensive guides, tutorials, and API references.
+- **[GitHub Issues](https://github.com/{{organization}}/{{project_name}}/issues):** Search existing issues to see if someone else has already reported your problem or requested your feature. Feel free to add a "+1" reaction to existing issues to show your interest.
+- **[GitHub Discussions](https://github.com/{{organization}}/{{project_name}}/discussions):** Search our discussions for Q&A, general advice, and community knowledge.
+
+## Opening a New Issue
+
+If you cannot find an answer in the documentation or existing issues, please open a new issue. To help us resolve your issue faster, please choose the correct venue:
+
+| Issue Type | Venue | Description |
+| :--- | :--- | :--- |
+| **Bug Report** | [GitHub Issues](https://github.com/{{organization}}/{{project_name}}/issues/new) | Use the "Bug Report" template. Provide reproducible steps, environment details, and relevant logs. |
+| **Feature Request** | [GitHub Issues](https://github.com/{{organization}}/{{project_name}}/issues/new) | Use the "Feature Request" template. Clearly describe your use case and the problem the feature would solve. |
+| **Q&A / General Help** | [GitHub Discussions](https://github.com/{{organization}}/{{project_name}}/discussions/new) | Start a discussion for questions about how to use `{{project_name}}`, architecture queries, or advice. |
+
+## Community Channels
+
+Join our community to chat with other users, contributors, and the core maintainers:
+
+- **[Discord / Slack / Matrix - Insert Link]**: Join our real-time chat server.
+- **[Mailing List / Forum - Insert Link]**: Subscribe for announcements and longer-form discussions.
+- **[Weekly Syncs - Insert Link]**: Join our community meetings (see our calendar for details).
+
+## Commercial Support
+
+
+At this time, there is no official commercial support available for `{{project_name}}`. Support is provided on a best-effort basis by the open-source community and maintainers.
diff --git a/llms.txt b/llms.txt
new file mode 100644
index 0000000..69340ed
--- /dev/null
+++ b/llms.txt
@@ -0,0 +1,20 @@
+# {{project_name}}
+
+> An opinionated, production-ready Apache 2.0 template repository for bootstrapping modern software projects.
+
+`{{project_name}}` is designed to eliminate boilerplate and enforce consistency across an organization's repositories.
+For comprehensive context and full documentation, please see [llms-full.txt](llms-full.txt).
+
+## Docs
+- [Home](https://{{organization}}.github.io/{{project_name}}/): Documentation site home page
+- [Getting Started](https://{{organization}}.github.io/{{project_name}}/getting-started/): Installation, quickstart, and workflow guides
+- [Guides](https://{{organization}}.github.io/{{project_name}}/guides/): How-to guides for common tasks
+- [API Reference](https://{{organization}}.github.io/{{project_name}}/reference/): Full API reference documentation
+
+## Repository Files
+- [README.md](https://github.com/{{organization}}/{{project_name}}/blob/main/README.md): Project overview and quick start
+- [AGENTS.md](https://github.com/{{organization}}/{{project_name}}/blob/main/AGENTS.md): AI agent coding instructions
+- [DEVELOPING.md](https://github.com/{{organization}}/{{project_name}}/blob/main/DEVELOPING.md): Developer setup guide
+
+## Optional
+- [Full Documentation](https://{{organization}}.github.io/{{project_name}}/llms-full.txt): The complete concatenated documentation for {{project_name}}
diff --git a/mkdocs.yml b/mkdocs.yml
new file mode 100644
index 0000000..e2b5fe3
--- /dev/null
+++ b/mkdocs.yml
@@ -0,0 +1,120 @@
+site_name: "{{ project_name }}"
+site_description: "{{ project_description }}"
+site_author: "{{ org_name }}"
+site_url: "https://{{ org_name }}.github.io/{{ project_name }}/"
+
+repo_url: "https://github.com/{{ org_name }}/{{ project_name }}"
+repo_name: "{{ org_name }}/{{ project_name }}"
+edit_uri: edit/main/docs/
+
+# ---------------------------------------------------------------------------
+# Template Variables — Update these when using this template.
+# All {{ variable }} references across the docs site are driven from here.
+# ---------------------------------------------------------------------------
+extra:
+ project_name: "{{project_name}}"
+ project_description: "{{project_description}}"
+ org_name: "{{organization}}"
+ org_email: "conduct@{{organization}}.com"
+ docs_url: "https://{{organization}}.github.io/{{project_name}}"
+ min_python: "3.9"
+ current_major_version: "0"
+ slack_url: "https://slack.{{organization}}.org"
+ blog_url: "https://blog.{{organization}}.org"
+ roadmap_url: "https://github.com/{{organization}}/{{project_name}}/milestones"
+
+theme:
+ name: material
+ features:
+ - navigation.tabs
+ - navigation.tabs.sticky
+ - navigation.sections
+ - navigation.expand
+ - navigation.top
+ - navigation.indexes
+ - search.suggest
+ - search.highlight
+ - search.share
+ - content.code.copy
+ - content.action.edit
+ - content.tooltips
+ palette:
+ # Palette toggle for light mode
+ - media: "(prefers-color-scheme: light)"
+ scheme: default
+ primary: indigo
+ accent: indigo
+ toggle:
+ icon: material/brightness-7
+ name: Switch to dark mode
+ # Palette toggle for dark mode
+ - media: "(prefers-color-scheme: dark)"
+ scheme: slate
+ primary: indigo
+ accent: indigo
+ toggle:
+ icon: material/brightness-4
+ name: Switch to light mode
+
+markdown_extensions:
+ - pymdownx.highlight:
+ anchor_linenums: true
+ line_spans: __span
+ pygments_lang_class: true
+ - pymdownx.inlinehilite
+ - pymdownx.snippets:
+ base_path: ["."]
+ - pymdownx.superfences:
+ custom_fences:
+ - name: mermaid
+ class: mermaid
+ format: !!python/name:pymdownx.superfences.fence_code_format
+ - admonition
+ - pymdownx.details
+ - pymdownx.tabbed:
+ alternate_style: true
+ - attr_list
+ - md_in_html
+ - tables
+ - toc:
+ permalink: true
+
+plugins:
+ - search
+ - macros
+
+nav:
+ - Home: index.md
+ - Getting Started:
+ - getting-started/index.md
+ - Installation: getting-started/installation.md
+ - Quick Start: getting-started/quickstart.md
+ - Workflows: getting-started/workflows.md
+ - Guides: guides/index.md
+ - Examples: examples/index.md
+ - Reference: reference/index.md
+ - Community:
+ - community/index.md
+ - Contributing: community/contributing.md
+ - Developer Setup: community/developing.md
+ - AI Agent Guide: community/agents.md
+ - Code of Conduct: community/code-of-conduct.md
+ - Security Policy: community/security.md
+ - Support: community/support.md
+
+extra_css:
+ - stylesheets/extra.css
+
+extra_javascript:
+ - scripts/extra.js
+
+# ---------------------------------------------------------------------------
+# LLM & AI Tooling
+# ---------------------------------------------------------------------------
+# llms.txt (root-level file) is served at /llms.txt on the deployed docs site.
+# It follows the llmstxt.org specification and provides a curated, machine-
+# readable index of documentation for LLM consumers and AI coding agents.
+# A companion file, llms-full.txt, contains the concatenated documentation.
+# The root AGENTS.md contains agent-specific coding instructions; it is also
+# surfaced in the docs nav under Community > AI Agent Guide.
+# ---------------------------------------------------------------------------
diff --git a/scripts/README.md b/scripts/README.md
new file mode 100644
index 0000000..2bed465
--- /dev/null
+++ b/scripts/README.md
@@ -0,0 +1,49 @@
+# `{{project_name}}` - Utility Scripts
+
+This directory contains utility scripts designed to assist with local development, maintenance, and automation tasks for `{{project_name}}`.
+
+> [!NOTE]
+> These scripts are intended for developer and CI/CD use only and are **not** distributed as part of the final application package.
+
+
+## Usage Guidelines
+
+To ensure a consistent development experience across the organization, please adhere to the following guidelines when running or adding scripts.
+
+### Execution
+
+Scripts should generally be executed from the root of the repository to ensure relative paths resolve correctly:
+
+```bash
+# Example
+./scripts/setup_dev_env.sh
+```
+
+Ensure the script has execution permissions before running:
+
+```bash
+chmod +x scripts/.sh
+```
+
+### Scripting Standards
+
+If you are adding or modifying a script in this directory, please ensure it adheres to the following best practices:
+
+- **Prefer Bash (`.sh`) or Python (`.py`):** These languages provide the best cross-platform compatibility.
+- **Fail Fast (Bash):** Always begin Bash scripts with `set -euo pipefail` to ensure they exit immediately on errors, undefined variables, or pipeline failures.
+- **Environment Variables:** If your script requires secrets or environment-specific configurations, document them at the top of the script and ensure they align with the `.env.example` file.
+- **Provide Help:** Scripts should ideally accept a `-h` or `--help` flag that outputs usage instructions.
+- **Log Clearly:** Prefix output with `[INFO]`, `[WARN]`, or `[ERROR]` to make CI/CD logs easier to read.
+
+
+## Available Scripts
+
+| Script | Description |
+| :--- | :--- |
+| `setup_dev_env.sh` | *(Example)* Bootstraps the local development environment. |
+| `release.sh` | *(Example)* Automates the version bumping and release tagging process. |
+
+
+## Contributing
+
+If you add a new utility script that would benefit other developers, please add it to the **Available Scripts** table above with a brief description of its purpose.
diff --git a/scripts/bootstrap.sh b/scripts/bootstrap.sh
new file mode 100755
index 0000000..77d2d98
--- /dev/null
+++ b/scripts/bootstrap.sh
@@ -0,0 +1,130 @@
+#!/usr/bin/env bash
+# =============================================================================
+# bootstrap.sh — Template Initialization
+#
+# Automatically replaces all template placeholders (e.g., {{project_name}})
+# with your actual project values.
+#
+# Usage:
+# ./scripts/bootstrap.sh --project-name my-app --organization my-org
+# =============================================================================
+
+set -euo pipefail
+
+if [[ $# -eq 0 ]] || [[ "$1" == "-h" ]] || [[ "$1" == "--help" ]]; then
+ echo "Usage: $0 [OPTIONS]"
+ echo ""
+ echo "Bootstraps the repository by replacing template variables."
+ echo ""
+ echo "Options:"
+ echo " --project-name NAME Replacement for {{project_name}}"
+ echo " --project-desc DESC Replacement for {{project_description}}"
+ echo " --organization ORG Replacement for {{organization}}"
+ echo " --org-name ORG Replacement for {{org_name}}"
+ echo ""
+ echo "Example: $0 --project-name my-app --organization my-org"
+ exit 0
+fi
+
+PROJECT_NAME=""
+PROJECT_DESC=""
+ORGANIZATION=""
+ORG_NAME=""
+
+while [[ $# -gt 0 ]]; do
+ case "$1" in
+ --project-name)
+ if [[ $# -lt 2 ]] || [[ "$2" == -* ]]; then
+ echo "[ERROR] Option $1 requires a value."
+ echo "Use $0 --help for usage guidance."
+ exit 1
+ fi
+ PROJECT_NAME="$2"
+ shift 2
+ ;;
+ --project-desc)
+ if [[ $# -lt 2 ]] || [[ "$2" == -* ]]; then
+ echo "[ERROR] Option $1 requires a value."
+ echo "Use $0 --help for usage guidance."
+ exit 1
+ fi
+ PROJECT_DESC="$2"
+ shift 2
+ ;;
+ --organization)
+ if [[ $# -lt 2 ]] || [[ "$2" == -* ]]; then
+ echo "[ERROR] Option $1 requires a value."
+ echo "Use $0 --help for usage guidance."
+ exit 1
+ fi
+ ORGANIZATION="$2"
+ shift 2
+ ;;
+ --org-name)
+ if [[ $# -lt 2 ]] || [[ "$2" == -* ]]; then
+ echo "[ERROR] Option $1 requires a value."
+ echo "Use $0 --help for usage guidance."
+ exit 1
+ fi
+ ORG_NAME="$2"
+ shift 2
+ ;;
+ *)
+ echo "[ERROR] Unknown option: $1"
+ exit 1
+ ;;
+ esac
+done
+
+echo "[INFO] Starting repository bootstrap..."
+
+export PROJECT_NAME
+export PROJECT_DESC
+export ORGANIZATION
+export ORG_NAME
+
+python3 -c "
+import os, sys
+
+replacements = {
+ '{{project_name}}': os.environ.get('PROJECT_NAME', ''),
+ '{{project_description}}': os.environ.get('PROJECT_DESC', ''),
+ '{{organization}}': os.environ.get('ORGANIZATION', ''),
+ '{{org_name}}': os.environ.get('ORG_NAME', '')
+}
+
+# Filter out empty arguments
+replacements = {k: v for k, v in replacements.items() if v}
+
+if not replacements:
+ print('[INFO] No replacements provided. Use -h for options.')
+ sys.exit(0)
+
+ignore_dirs = {'.git', '.venv', 'node_modules', 'site', '__pycache__', 'assets'}
+ignore_exts = ('.pyc', '.png', '.svg', '.jpg', '.jpeg', '.gif', '.ico', '.woff', '.woff2', '.ttf', '.eot')
+
+for root, dirs, files in os.walk('.'):
+ dirs[:] = [d for d in dirs if d not in ignore_dirs]
+ for file in files:
+ if file.endswith(ignore_exts) or file == 'bootstrap.sh':
+ continue
+
+ filepath = os.path.join(root, file)
+
+ try:
+ with open(filepath, 'r', encoding='utf-8') as f:
+ content = f.read()
+ except UnicodeDecodeError:
+ continue
+
+ new_content = content
+ for placeholder, replacement in replacements.items():
+ new_content = new_content.replace(placeholder, replacement)
+
+ if content != new_content:
+ with open(filepath, 'w', encoding='utf-8') as f:
+ f.write(new_content)
+ print(f'[INFO] Updated: {filepath}')
+"
+
+echo "[INFO] Bootstrap complete! You may now delete this script if desired."
diff --git a/src/{{project_name}}/.gitkeep b/src/{{project_name}}/.gitkeep
new file mode 100644
index 0000000..8f8f5a1
--- /dev/null
+++ b/src/{{project_name}}/.gitkeep
@@ -0,0 +1 @@
+# This directory is for the main source code of the project.
diff --git a/tests/e2e/.gitkeep b/tests/e2e/.gitkeep
new file mode 100644
index 0000000..b5c8ce4
--- /dev/null
+++ b/tests/e2e/.gitkeep
@@ -0,0 +1 @@
+# This directory is for end-to-end tests.
diff --git a/tests/integration/.gitkeep b/tests/integration/.gitkeep
new file mode 100644
index 0000000..f045d29
--- /dev/null
+++ b/tests/integration/.gitkeep
@@ -0,0 +1 @@
+# This directory is for integration tests.
diff --git a/tests/unit/.gitkeep b/tests/unit/.gitkeep
new file mode 100644
index 0000000..d5b311d
--- /dev/null
+++ b/tests/unit/.gitkeep
@@ -0,0 +1 @@
+# This directory is for fast, isolated unit tests.
+ 
+
+
+ 
+
+
+