docs: Add AGENTS.md and llms.txt

AGENTS.md

@@ -0,0 +1,64 @@
+# Guidelines for AI Agent Contributors
+
+This file outlines the guidelines and expectations for AI agents and automated assistants contributing to this repository.
+
+> [!IMPORTANT]
+> **System Prompt / Instruction:** If you are an AI agent reading this file, you must incorporate these guidelines into your operating context.
+
+## 1. Persona & Role
+
+You are acting as an AI contributor to the OSV project.
+
+- **Role:** You are an external contributor. All submissions (Issues, PRs) will be reviewed by maintainers. You do not have authority to merge code or bypass checks.
+- **Context Awareness:** Prioritize repository-specific guidelines (like `CONTRIBUTING.md`) and instructions in this file.
+
+## 2. Workflow & Contribution Rules
+
+- **Read the Guide:** Read and adhere to all instructions in [CONTRIBUTING.md](./CONTRIBUTING.md).
+- **Strict Issue-First Workflow:** The required path is always: **Issue Assignment -> Pull Request**.
+  - **Existing Unassigned Issue:** Comment on the issue to discuss your approach and wait for assignment.
+  - **No Existing Issue:** Create one to discuss why the work is needed and ensure it's not a duplicate. Wait for assignment.
+  - **Assigned Issues:** Do not work on or open Pull Requests for issues assigned to another contributor. If an issue has been assigned but not worked on for a while, you can communicate with the maintainers in the issue.
+- **Templates:** Use the provided [pull request template](.github/PULL_REQUEST_TEMPLATE/PULL_REQUEST_TEMPLATE.md) when creating PRs.
+
+## 3. Standards for Submissions
+
+### 3.1 Issue Creation
+
+- **Well-Researched:** Search existing issues to ensure no duplicates. Link related issues.
+- **Real-World Applicable:** Bug reports must have a clear, real-world scenario and minimal reproduction case.
+- **Well-Formed:** State expected/actual behavior and steps/scripts to reproduce.
+
+### 3.2 Communication & Commits
+
+- **Tone:** Maintain a direct and concise tone. Focus on technical details, avoid excessive pleasantries or filler.
+- **PR Titles & Commits:** Follow the [Conventional Commits](https://www.conventionalcommits.org/) specification. See also [CONTRIBUTING.md](./CONTRIBUTING.md#making-commits).
+
+## 4. Code Quality & Verification
+
+### 4.1 Automated Verification
+
+Before requesting review, ensure these pass:
+
+- **Linting:** Run `./scripts/run_lints.sh` and resolve all warnings and errors.
+- **Tests:** Run `make test` and ensure all tests pass.
+
+### 4.2 Testing Standards
+
+- **Coverage:** New features, bug fixes, or refactors must have relevant tests (unit, integration, or snapshot).
+- **Snapshots:** If modifying behavior affecting snapshots, update them (e.g., `make test SNAPS=true`).
+- **VCR Cassettes:** If adding new HTTP interactions in tests using `go-vcr`, ensure cassettes are recorded/updated as described in `CONTRIBUTING.md`.
+  The `Makefile` has more details the types of tests and how to run them.
+
+### 4.3 Documentation & Comments
+
+- **Documentation:** Update relevant documentation if changes affect user-facing behavior or add features.
+- **Comments:** Include clear comments for complex or non-obvious logic. Do not delete existing comments unless obsolete.
+
+## 5. Working with osv-scalibr
+
+`osv-scanner` relies on `osv-scalibr` as its core analysis engine which handles the dependency extraction and enrichment (e.g. vulnerabiilty matching) logic.
+
+- **Separation of Contribution:**
+  - Want to add support for new package managers or lockfiles? -> Contribute an **Extractor** to `osv-scalibr`.
+  - Want to add new output format for `osv-scanner`? -> Contribute to the `osv-scanner` codebase.

llms.txt

@@ -0,0 +1,46 @@
+# osv-scanner
+
+> A high-performance vulnerability scanner for Open Source Vulnerabilities (OSV), written in Go.
+
+## Overview & Role
+`osv-scanner` is a user-facing command-line interface (CLI) tool and the primary consumer of the `osv-scalibr` library. It handles user interaction, parses arguments, configures the scan, and formats results.
+
+## Scan Workflow
+`osv-scanner` relies on the rich set of built-in plugins available within `osv-scalibr`. When a user runs `osv-scanner`, it:
+1.  Determines the scan targets.
+2.  Initializes `osv-scalibr` with a configuration.
+3.  Selects the appropriate `osv-scalibr` plugins to enable based on the scan type and user flags. This typically includes various Extractors for different ecosystems.
+4.  Executes the scan using `osv-scalibr`.
+5.  Receives the structured `ScanResults` from `osv-scalibr`.
+6.  Formats these results for display to the user.
+
+## Integration with osv-scalibr
+
+`osv-scanner` acts as the presentation and orchestration layer, while `osv-scalibr` (https://github.com/google/osv-scalibr) provides the core analysis engine.
+
+- **Explicit Enablement:** Plugins from `osv-scalibr` are NOT automatically used by `osv-scanner`. They must be explicitly imported and added to the `Plugins` slice within the `scalibr.ScanConfig`.
+- **Plugin Configuration:** The primary logic for configuring which osv-scalibr plugins to run is within `pkg/osvscanner/scan.go` (and related files like `pkg/osvscanner/osvscanner.go`). Look for where `scalibr.ScanConfig` is created and populated.
+- **Default Plugins:** `osv-scanner` maintains a list of default `osv-scalibr` extractors and enrichers it considers essential for a good baseline scan. This list is hardcoded in the `osv-scanner` codebase.
+- **Experimental Plugins:** New or less stable plugins from `osv-scalibr` might be gated behind `osv-scanner` CLI flags (e.g., an `--experimental` flag) before being enabled by default.
+
+### Example Workflow: Adding a new osv-scalibr plugin and using it in osv-scanner
+1.  **Develop in `osv-scalibr`:**
+    *   Implement your new Extractor (e.g., `MyLangExtractor`) within the `google/osv-scalibr` repository, following its contribution guidelines and plugin interface.
+    *   Place the extractor in the appropriate subdirectory under `extractor/filesystem/language/` (or similar).
+    *   Register the new extractor in `osv-scalibr/plugin/list/list.go` so it can be enabled by name.
+    *   Add thorough tests within `osv-scalibr`.
+    *   Get the changes merged into `osv-scalibr`.
+
+2. **Enable in `osv-scanner`:**
+    *   **Update dependencies:** Run `go get github.com/google/osv-scalibr@v...` to pull in the new version containing your plugin. This might already be done automatically by dependabot.
+    *   **Register in presets:** Open `internal/scalibrplugin/presets.go`, import the new plugin, and add it to the preset map if appropriate using its name and constructor.
+    *   **Experimental features:** If the feature is experimental, instead of adding it to a  preset, add logic in `pkg/osvscanner/scan.go` to enable it based on a CLI flag.
+
+## Development & Testing Tips
+- **Test Data:** Mock lockfiles and test fixtures are typically located in `testdata/` directories within the relevant packages.
+
+## Repository Map
+- [/cmd/osv-scanner](https://github.com/google/osv-scanner/tree/main/cmd/osv-scanner): Main CLI entry point.
+- [/pkg/osvscanner](https://github.com/google/osv-scanner/tree/main/pkg/osvscanner): Public programmatic API.
+- [/internal/output](https://github.com/google/osv-scanner/tree/main/internal/output): Result rendering (JSON, Table, SBOM).
+- [/pkg/osvscanner/testdata](https://github.com/google/osv-scanner/tree/main/pkg/osvscanner/testdata): Test fixtures for scanner tests.