Reorganize documentation as self-contained markdown (no GitHub Pages) (#42)

* feat: Updates Docs

Author: vineethsai7

.github/workflows/scan-skills.yml

@@ -187,7 +187,7 @@ jobs:
 
       - name: Upload SARIF to Code Scanning
         if: inputs.upload_sarif && inputs.format == 'sarif' && hashFiles('results.sarif') != ''
-        uses: github/codeql-action/upload-sarif@v3
+        uses: github/codeql-action/upload-sarif@v4
         with:
           sarif_file: results.sarif
 

README.md

@@ -37,7 +37,7 @@ Skill Scanner is a detection tool. It identifies known and probable risk pattern
 
 - **No findings ≠ no risk.** A scan that returns "No findings" indicates that no known threat patterns were detected. It does not guarantee that a skill is secure, benign, or free of vulnerabilities.
 - **Coverage is inherently incomplete.** The scanner combines signature-based detection, LLM-based semantic analysis, behavioral dataflow analysis, optional cloud services, and configurable rule packs. While this approach improve coverage, no automated tool can detect every technique, especially novel or zero-day attacks.
-- **False positives and false negatives can occur.** Consensus modes and meta-analysis reduce noise, but no configuration eliminates all incorrect classifications. Tune the [scan policy](docs/scan-policy.md) to your risk tolerance.
+- **False positives and false negatives can occur.** Consensus modes and meta-analysis reduce noise, but no configuration eliminates all incorrect classifications. Tune the [scan policy](docs/user-guide/custom-policy-configuration.md) to your risk tolerance.
 - **Human review remains essential.** Automated scanning is one component of a defense-in-depth strategy. High-risk or production deployments should pair scanner results with manual code review and/or  threat modeling.
 
 ---
@@ -46,18 +46,18 @@ Skill Scanner is a detection tool. It identifies known and probable risk pattern
 
 | Guide | Description |
 |-------|-------------|
-| [Quick Start](docs/quickstart.md) | Get started in 5 minutes |
-| [Architecture](docs/architecture.md) | System design and components |
-| [Threat Taxonomy](docs/threat-taxonomy.md) | Complete AITech threat taxonomy with examples |
-| [LLM Analyzer](docs/llm-analyzer.md) | LLM configuration and usage |
-| [Meta-Analyzer](docs/meta-analyzer.md) | False positive filtering and prioritization |
-| [Behavioral Analyzer](docs/behavioral-analyzer.md) | Dataflow analysis details |
-| [Scan Policy](docs/scan-policy.md) | Custom policies, presets, and tuning guide |
-| [Policy Quick Reference](docs/POLICY.md) | Compact reference for policy sections and knobs |
-| [Rule Authoring](docs/AUTHORING.md) | How to add signature, YARA, and Python rules |
+| [Quick Start](docs/getting-started/quick-start.md) | Get started in 5 minutes |
+| [Architecture](docs/architecture/index.md) | System design and components |
+| [Threat Taxonomy](docs/architecture/threat-taxonomy.md) | Complete AITech threat taxonomy with examples |
+| [LLM Analyzer](docs/architecture/analyzers/llm-analyzer.md) | LLM configuration and usage |
+| [Meta-Analyzer](docs/architecture/analyzers/meta-analyzer.md) | False positive filtering and prioritization |
+| [Behavioral Analyzer](docs/architecture/analyzers/behavioral-analyzer.md) | Dataflow analysis details |
+| [Scan Policy](docs/user-guide/custom-policy-configuration.md) | Custom policies, presets, and tuning guide |
+| [Policy Quick Reference](docs/reference/policy-quick-reference.md) | Compact reference for policy sections and knobs |
+| [Rule Authoring](docs/architecture/analyzers/writing-custom-rules.md) | How to add signature, YARA, and Python rules |
 | [GitHub Actions](docs/github-actions.md) | Reusable workflow for CI/CD integration |
-| [API Reference](docs/api-server.md) | REST API documentation |
-| [Development Guide](docs/developing.md) | Contributing and development setup |
+| [API Reference](docs/user-guide/api-server.md) | REST API documentation |
+| [Development Guide](docs/development/setup-and-testing.md) | Contributing and development setup |
 
 ---
 
@@ -180,7 +180,7 @@ skill-scanner configure-policy
 ```
 
 **LLM provider note:** `--llm-provider` currently accepts `anthropic` or `openai`.
-For Bedrock, Vertex, Azure, Gemini, and other LiteLLM backends, set provider-specific model strings and environment variables (see `docs/llm-analyzer.md`).
+For Bedrock, Vertex, Azure, Gemini, and other LiteLLM backends, set provider-specific model strings and environment variables (see [LLM Analyzer docs](docs/architecture/analyzers/llm-analyzer.md)).
 
 ### Python SDK
 

docs/README.md

@@ -0,0 +1,67 @@
+# Skill Scanner Documentation
+
+Security scanning for AI agent skills. Detects prompt injection, data exfiltration, and malicious code patterns with multi-engine analysis.
+
+## Getting Started
+
+- [Quick Start](getting-started/quick-start.md) -- Install, configure, and run your first scan
+
+## Architecture
+
+- [Overview](architecture/index.md) -- System design, scanning pipeline, and risk model
+- [Scanning Pipeline](architecture/scanning-pipeline.md) -- How files flow through the analysis stages
+- [Threat Taxonomy](architecture/threat-taxonomy.md) -- AITech threat taxonomy with examples
+- [Binary Handling](architecture/binary-handling.md) -- How compiled and binary files are processed
+
+### Analyzers
+
+- [Analyzer Overview](architecture/analyzers/index.md) -- Summary of all available analyzers
+- [Static Analyzer](architecture/analyzers/static-analyzer.md) -- YAML + YARA pattern matching
+- [Behavioral Analyzer](architecture/analyzers/behavioral-analyzer.md) -- AST dataflow analysis
+- [LLM Analyzer](architecture/analyzers/llm-analyzer.md) -- LLM-as-a-judge semantic analysis
+- [Meta-Analyzer](architecture/analyzers/meta-analyzer.md) -- False positive filtering and prioritization
+- [Meta & External Analyzers](architecture/analyzers/meta-and-external-analyzers.md) -- AI Defense, VirusTotal, and meta-analysis
+- [AI Defense Analyzer](architecture/analyzers/aidefense-analyzer.md) -- Cisco AI Defense cloud analyzer
+- [Writing Custom Rules](architecture/analyzers/writing-custom-rules.md) -- Author YAML signatures, YARA rules, and Python checks
+
+## Concepts
+
+- [Security Model](concepts/security-model.md) -- Threat model and security assumptions
+- [Remote Skills Analysis](concepts/remote-skills-analysis.md) -- Scanning skills fetched from remote sources
+
+## Features
+
+- [Feature Overview](features/index.md) -- All scanner capabilities at a glance
+
+## User Guide
+
+- [User Guide Overview](user-guide/index.md) -- Getting the most out of Skill Scanner
+- [Installation & Configuration](user-guide/installation-and-configuration.md) -- Setup and environment
+- [CLI Usage](user-guide/cli-usage.md) -- Command-line interface
+- [Python SDK](user-guide/python-sdk.md) -- Programmatic scanning
+- [API Server](user-guide/api-server.md) -- REST API server
+- [API Operations](user-guide/api-operations.md) -- API usage patterns
+- [API Endpoints Detail](user-guide/api-endpoints-detail.md) -- Endpoint reference
+- [API Rationale](user-guide/api-rationale.md) -- Design decisions behind the API
+- [Scan Policies Overview](user-guide/scan-policies-overview.md) -- Policy presets and tuning
+- [Custom Policy Configuration](user-guide/custom-policy-configuration.md) -- Writing your own policy YAML
+
+## Guides
+
+- [Examples & How-To](guides/examples-and-how-to.md) -- Common workflows and recipes
+
+## Reference
+
+- [Reference Overview](reference/index.md) -- Quick links to all reference material
+- [CLI Command Reference](reference/cli-command-reference.md) -- All commands and options
+- [API Endpoint Reference](reference/api-endpoint-reference.md) -- REST API endpoints
+- [Configuration Reference](reference/configuration-reference.md) -- Environment variables and config
+- [Output Formats](reference/output-formats.md) -- JSON, SARIF, Markdown, HTML, and table formats
+- [Policy Quick Reference](reference/policy-quick-reference.md) -- Compact policy section and knob reference
+- [Dependencies & LLM Providers](reference/dependencies-and-llm-providers.md) -- Supported providers and extras
+
+## Development
+
+- [Development Overview](development/index.md) -- Contributing to Skill Scanner
+- [Setup & Testing](development/setup-and-testing.md) -- Dev environment and test suite
+- [Integrations](development/integrations.md) -- CI/CD, GitHub Code Scanning, and more