Merge pull request #27 from cosai-oasis/docs/owasp-vs-core

docs: added owasp vs core and rule types section

Author: ramraaj25

docs/faq.md

@@ -40,11 +40,26 @@ This FAQ document provides clear, concise answers to help developers seamlessly
   </sub>
 </center>
 
+---
+
+## Q: What is the difference between always-on rules and glob-scoped rules?
+
+**A:** They are two activation types:
+
+- **Always-on** rules apply to all files and provide a baseline security guardrail.
+- **Glob-scoped** rules apply only to files matching their language/file patterns.
 
 ---
+
 ## Q: What are the OWASP supplementary rules?
 
-**A:** The `sources/owasp/` folder contains supplementary rules based on OWASP cheat sheets. These rules supplement the core security rules and can be optionally included when building from source. By default, only core rules (22 files) are included in standard builds.
+**A:** The `sources/owasp/` folder contains supplementary rules based on OWASP guidance that informed the original rule development. These rules are optional, not enabled by default, and are intended primarily for reference and deeper security review use cases.
+
+The official release bundles package the main `sources/core/` rules. If you [build from source](getting-started.md#option-2-build-from-source) and want the OWASP supplementary set too, include it explicitly:
+
+```bash
+uv run python src/convert_to_ide_formats.py --source core owasp
+```
 
 ---
 

docs/getting-started.md

@@ -136,6 +136,22 @@ cp -r dist/.github/ /path/to/your/project/
 cp -r dist/.agent/ /path/to/your/project/
 ```
 
+## Core vs OWASP Sources
+
+Project CodeGuard has two source rule sets:
+
+- `sources/core/`: Official Project CodeGuard rules. These are the main rules packaged in releases and enabled by default.
+- `sources/owasp/`: Supplementary rules originally derived from OWASP guidance. These are optional and are not enabled by default.
+
+Use OWASP supplementary rules when you explicitly want broader coverage, such as deeper security reviews or reference-driven review workflows.
+
+## Rule Types: Always-On vs Glob-Scoped
+
+Project CodeGuard supports two rule activation types:
+
+- **Always-on rules**: Apply to all files in the project. These rules are for baseline safeguards that should always be in context.
+- **Glob-scoped rules**: Apply only to matching file patterns (derived from `languages` in source frontmatter). These rules are for language- or framework-specific guidance.
+
 ## Keeping Rules Updated (Automated)
 
 For GitHub repositories, you can automate rule updates with a workflow that runs monthly and creates PRs when new versions are available.