diff --git a/FAQ.md b/FAQ.md
index 63afe54..ba087f7 100644
--- a/FAQ.md
+++ b/FAQ.md
@@ -1,5 +1,11 @@
# Frequently Asked Questions
+## Version Control System support
+
+### Q: Do you support version control platforms other than GitHub?
+
+**A:** Currently this project only supports projects hosted on GitHub.
+
## Release Workflow Issues
### Q: Why is my release workflow failing with permission errors?
@@ -42,13 +48,15 @@ Ensure your commits follow the format:
### 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 projects. If you need a specific version, ensure your commits indicate the appropriate change level.
+**A:** No, the workflow is designed to automatically determine the version based on conventional commits. This ensures consistent versioning across all
+projects. If you need a specific version, ensure your commits indicate the appropriate change level.
## Project Generation Issues
### Q: Why does project generation fail during the release step?
**A:** The post-generation hook attempts to create an initial release. This requires:
+
1. GitHub CLI (`gh`) to be installed and authenticated
2. A valid GitHub token with repository write permissions
3. The repository to exist on GitHub
@@ -56,20 +64,25 @@ Ensure your commits follow the format:
To skip the automatic release during local testing, you have two options:
1. **Recommended**: Run the hook but skip only the git push:
+
```bash
export SKIP_GIT_PUSH=true
```
+
This allows the post-generation hook to set up your project correctly while avoiding push failures.
2. **Not recommended**: Skip the entire post-generation hook:
+
```bash
export RUN_POST_HOOK=false
```
+
β οΈ This will skip important setup steps like git initialization, dependency locking, and project configuration.
### Q: Why does the post-generation hook fail to push to main?
-**A:** If your repository has branch protection rules that prevent direct pushes to main from local development, the post-generation hook will fail when trying to push the initial commit.
+**A:** If your repository has branch protection rules that prevent direct pushes to main from local development, the post-generation hook will fail when trying
+to push the initial commit.
#### Solution:
diff --git a/README.md b/README.md
index 11033e0..ac735e2 100644
--- a/README.md
+++ b/README.md
@@ -1,54 +1,57 @@
-# AI-Native Python
+
+AI-Native Python
-[](https://github.com/zenable-io/ai-native-python/actions/workflows/ci.yml)
+AI-Native Python sets you on a paved road of automated guardrails, where each commit is instantly checked for security, quality, and compliance.
-Give your vibe coding the perfect starting point with this paved-road repo generator so Cursor (or any AI) can learn by exampleβno verbose prompts needed.
+It works seamlessly with GitHub Copilot, Cursor, Claude, Windsurf, and other leading AI coding agents to route their output through fully instrumented pipelines
+of tests, security scans, and release automation.
+
+Make your tools meet every requirement on the first pass, letting you ship faster without loosening safety or standards.
## Features
-- π Modern Python development with `uv`
-- π§ͺ Automated testing with `pytest`
-- π Code quality checks with `pre-commit` hooks (`ruff`, `pyright`, etc.)
-- π Security scanning with SBOM generation (`syft`), vulnerability scanning (`grype`), and license checks (`grant`)
-- π€ Automated dependency updates with Dependabot and Renovate
-- π¦ Multi-platform Docker builds
+- π Modern, lightning fast Python development with `uv`
+- π§ͺ Automated testing with `pytest` with 100% coverage
+- π Code quality checks on every commit with `pre-commit`
+- π Security scanning with SBOM generation, vulnerability scanning, and license checks
+- π€ Never think about upstream vulnerabilities again with **automated dependency upgrades**
+- π¦ 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 FAQs including release workflow troubleshooting, see our [FAQ documentation](./FAQ.md)
## Getting Started
-Create an empty remote Git repository that aligns with name of the project you'd like to create. Once it exists, you can continue.
+1. Create an [empty GitHub repository](https://docs.github.com/en/repositories/creating-and-managing-repositories/creating-a-new-repository)
+1. Generate a project with the same name as the repo you just made:
-```bash
-# Install the prerequisites
-brew install uv
+ ```bash
+ # Install the prerequisites
+ brew install uv
-# Initialize your project
-uvx --with gitpython cookiecutter gh:zenable-io/ai-native-python
-```
+ # Initialize your project
+ uvx --with gitpython cookiecutter gh:zenable-io/ai-native-python
+ ```
-If you'd like to use SSH instead of HTTPS, use this command instead:
+1. Review your newly populated GitHub repository π
-```bash
-uvx --with gitpython cookiecutter git+ssh://git@github.com/zenable-io/ai-native-python.git
-```
+## Next Steps
-This will push the initial commit and run a release of your project; ensure that this succeeds before adding business logic to ensure you have a solid
-foundation.
+Now that you've generated the initial repository you can configure any required repository settings such as rulesets/branch protections. This can be done via
+Infrastructure as Code (IaC) or manually, but ostensibly by this point your repository is aligned with your organizational practices and you're ready to start
+adding features.
-Then, configure any required repository settings such as rulesets/branch protections. This can be done via Infrastructure as Code (IaC) or manually, but
-ostensibly by this point your repository is aligned with your organizational practices and you're ready to start adding features.
+> [!TIP]
+> Consider a tool like OpenSSF [allstar](https://github.com/ossf/allstar) to monitor these settings automatically.
-Consider a tool like OpenSSF [allstar](https://github.com/ossf/allstar) to monitor and alert or mitigate on your behalf.
+### Adding a feature
+
+To make a change to the project, just replace the `NotImplementedError` placeholder and you're all set!
```bash
# Enter the project directory
cd $(ls -td * | head -1)
-# Initialize the repository
-task init
-
# Checkout a new branch for your initial content
git checkout -b initial-content
@@ -56,10 +59,12 @@ git checkout -b initial-content
grep -r NotImplementedError *
```
-## Optional setup
+### Optional setup
If you'd like to support license file checking locally, you will need to install `grant` and put it in your `PATH`
-## Version Control System support
+Additionally, if you'd like to use SSH instead of HTTPS to connect to the `ai-native-python` project, use this command instead:
-Currently this project only supports projects hosted on GitHub.
+```bash
+uvx --with gitpython cookiecutter git+ssh://git@github.com/zenable-io/ai-native-python.git
+```
diff --git a/img/ai-native-python.png b/img/ai-native-python.png
new file mode 100644
index 0000000..df046a1
Binary files /dev/null and b/img/ai-native-python.png differ