docs: add user-facing component guides (#57)

Author: bomly-guy

Makefile

@@ -6,7 +6,7 @@ GOPATH_BIN=$(shell go env GOPATH)/bin
 EXE_SUFFIX=$(if $(filter Windows_NT,$(OS)),.exe,)
 GOLANGCI_LINT=$(GOPATH_BIN)/golangci-lint$(EXE_SUFFIX)
 
-.PHONY: build build-full build-lite fmt fmt-check lint install-hooks test run generate docs-config docs-schema docs-schema-md docs-support-matrix smoke qa licenses
+.PHONY: build build-full build-lite fmt fmt-check lint install-hooks test run generate docs-config docs-schema docs-schema-md docs-support-matrix docs-components smoke qa licenses
 
 build: build-full build-lite
 
@@ -43,7 +43,7 @@ qa: build-full
 run:
 	go run ./cmd/bomly $(ARGS)
 
-generate: docs-config docs-schema docs-schema-md docs-support-matrix
+generate: docs-config docs-schema docs-schema-md docs-support-matrix docs-components
 
 docs-config:
 	go run ./internal/support/cmd/configref
@@ -57,6 +57,9 @@ docs-schema-md:
 docs-support-matrix:
 	go run ./internal/support/cmd/supportmatrix
 
+docs-components:
+	go run ./internal/support/cmd/componentdocs
+
 licenses:
 	go run github.com/google/go-licenses@$(GO_LICENSES_VERSION) save ./... \
 		--save_path=./licenses \

README.md

@@ -111,6 +111,14 @@ Bomly has native detectors for:
 
 Bomly also supports many additional ecosystems through Syft-backed detection. See [docs/SUPPORT_MATRIX.md](docs/SUPPORT_MATRIX.md) for the generated matrix.
 
+For user-friendly component guides, see:
+
+- [Detectors](docs/DETECTORS.md): how Bomly finds package-manager evidence and builds dependency graphs
+- [Matcher guides](docs/MATCHERS.md): how optional enrichment adds vulnerabilities, licenses, and lifecycle data
+- [Auditors](docs/AUDITORS.md): how `--audit` turns existing vulnerability data into findings
+- [Detector ecosystem guides](docs/detectors/ecosystems/README.md): generated per-ecosystem detector chains and evidence patterns
+- [Matcher reference](docs/matchers/README.md): generated per-matcher behavior and output notes
+
 ## Core Commands
 
 ### `bomly scan`
@@ -129,8 +137,13 @@ bomly scan --sbom --path ./existing-sbom.json
 
 # Filter to runtime dependencies only
 bomly scan --scope runtime
+
+# Explore the result in the interactive terminal UI
+bomly scan --interactive
 ```
 
+`scan` is offline-safe unless you opt into enrichment. Use `--enrich` when you want Bomly to call external vulnerability, license, or lifecycle services. Use `--audit` when you want Bomly to evaluate vulnerability data that already exists on packages. Use both together when you want fetched vulnerability data evaluated in one run.
+
 ### `bomly explain`
 
 Use `explain` to show the dependency path that introduced a package.

docs/AUDITORS.md

@@ -0,0 +1,15 @@
+# Auditors
+
+Auditors evaluate a graph and produce findings.
+
+The default policy auditor looks at vulnerability data that is already present on packages. It does not make network calls on its own. If you want Bomly to fetch vulnerability data and then evaluate policy in one command, run `bomly scan --enrich --audit`.
+
+## When Auditors Run
+
+- `bomly scan --audit` evaluates the full graph.
+- `bomly explain --audit` evaluates the selected component context.
+- `bomly diff --audit` classifies introduced, resolved, and persisted findings.
+
+## Findings
+
+Findings have a normalized shape: ID, kind, severity, package, title, reasons, and source. Text output summarizes them for humans, JSON exposes them for automation, and SARIF is available for audit results with `--format sarif`.

docs/DETECTORS.md

@@ -0,0 +1,22 @@
+# Detectors
+
+Detectors are the part of Bomly that read a project, container, or SBOM and turn the evidence into a dependency graph.
+
+Bomly plans detector work before a scan starts. It looks for package-manager evidence such as lockfiles, manifests, workflow files, or SBOM documents, then runs the best detector chain for each discovered subproject. Native detectors run first when Bomly can produce a richer graph itself. Syft-backed detection fills coverage gaps and container/image scenarios.
+
+## When Detectors Run
+
+- `bomly scan` runs detectors to build the graph.
+- `bomly explain` reuses the same detector planning before finding dependency paths.
+- `bomly diff` runs detectors for each side of the comparison unless you diff SBOM files.
+- Detector plugins participate in the same planning flow when they declare package-manager evidence.
+
+## Detector Chains
+
+A detector chain is the ordered list Bomly tries for a package manager. The first detector is preferred. A later detector is a fallback when the preferred detector is not ready, not applicable, or cannot produce graph data.
+
+Some detectors can run an ecosystem tool such as `npm`, `go`, `mvn`, `dart`, `swift`, or `sbt`. Bomly does not install package managers for you. Use `--install-first` only when you want detectors that support it to run their normal dependency-install command before resolving the graph.
+
+## Generated Ecosystem Guides
+
+The pages in `docs/detectors/ecosystems/` are generated from Bomly's registry. Each page lists supported package managers, evidence patterns, chain order, install-first support, and the native commands users may need on `PATH`.

docs/MATCHERS.md

@@ -0,0 +1,15 @@
+# Matchers
+
+Matchers enrich packages after Bomly has built a dependency graph.
+
+Bomly is offline-safe by default. Network-backed matchers only run when package enrichment is explicitly enabled, for example with `bomly scan --enrich`. Matchers attach data such as vulnerabilities, license metadata, and end-of-life signals to packages. Auditors can then evaluate the enriched graph when `--audit` is enabled.
+
+## What Matchers Add
+
+- Vulnerability matchers add vulnerability IDs, severity, aliases, CVSS, fixed versions, references, and KEV signals where available.
+- License matchers add license evidence from external package metadata services.
+- Lifecycle matchers add ecosystem/runtime end-of-life metadata.
+
+## Generated Matcher Guides
+
+The pages in `docs/matchers/` are generated from Bomly's matcher descriptors and known runtime behavior. They list when each matcher runs, whether it uses the network, cache expectations, and the output fields users should expect.

docs/README.md

@@ -0,0 +1,19 @@
+# Bomly Documentation
+
+Start here when you want to understand what Bomly scans, what it adds, and which output to use.
+
+## Guides
+
+- [Support Matrix](SUPPORT_MATRIX.md): generated overview of supported ecosystems and package managers
+- [Detectors](DETECTORS.md): how Bomly discovers projects and builds dependency graphs
+- [Matchers](MATCHERS.md): how optional enrichment adds vulnerability, license, and lifecycle data
+- [Auditors](AUDITORS.md): how Bomly turns vulnerability data into findings
+- [Managed Plugins](PLUGINS.md): install, enable, verify, and run external detectors, matchers, and auditors
+- [CI](CI.md): validation, smoke tests, release packaging, and automation notes
+
+## Generated References
+
+- [Config Reference](CONFIG_REFERENCE.md)
+- [Detector ecosystem guides](detectors/ecosystems/README.md)
+- [Matcher reference](matchers/README.md)
+- [JSON schema docs](schemas/scan.md)

docs/detectors/ecosystems/README.md

@@ -0,0 +1,36 @@
+# Detector Ecosystem Guides
+
+These generated pages explain how Bomly detects each supported ecosystem.
+
+- [alpm](alpm.md)
+- [apk](apk.md)
+- [conda](conda.md)
+- [cpp](cpp.md)
+- [dart](dart.md)
+- [dotnet](dotnet.md)
+- [dpkg](dpkg.md)
+- [elixir](elixir.md)
+- [erlang](erlang.md)
+- [github-actions](github-actions.md)
+- [go](go.md)
+- [haskell](haskell.md)
+- [homebrew](homebrew.md)
+- [lua](lua.md)
+- [maven](maven.md)
+- [nix](nix.md)
+- [npm](npm.md)
+- [ocaml](ocaml.md)
+- [php](php.md)
+- [portage](portage.md)
+- [prolog](prolog.md)
+- [python](python.md)
+- [r](r.md)
+- [rpm](rpm.md)
+- [ruby](ruby.md)
+- [rust](rust.md)
+- [sbom](sbom.md)
+- [scala](scala.md)
+- [snap](snap.md)
+- [swift](swift.md)
+- [terraform](terraform.md)
+- [wordpress](wordpress.md)

docs/detectors/ecosystems/alpm.md

@@ -0,0 +1,16 @@
+# Alpm Detectors
+
+<!-- Auto-generated by make generate. Do not edit manually. -->
+
+Bomly uses these detector chains when it finds `alpm` package-manager evidence.
+
+| Package manager | Detector chain | Evidence patterns | Install-first support | Native command hints |
+| --- | --- | --- | --- | --- |
+| `alpm` | `syft-detector` | `var/lib/pacman/local/*/desc` | No | `syft for bomly-lite` |
+
+## How To Read This
+
+- Bomly tries detector chains from left to right.
+- Evidence patterns are files or paths Bomly uses during planning.
+- Install-first support means `--install-first` can run the ecosystem's normal install command before graph resolution.
+- Syft-backed entries provide broad compatibility, especially for containers and ecosystems without native Bomly graph resolution.

docs/detectors/ecosystems/apk.md

@@ -0,0 +1,16 @@
+# Apk Detectors
+
+<!-- Auto-generated by make generate. Do not edit manually. -->
+
+Bomly uses these detector chains when it finds `apk` package-manager evidence.
+
+| Package manager | Detector chain | Evidence patterns | Install-first support | Native command hints |
+| --- | --- | --- | --- | --- |
+| `apk` | `syft-detector` | `lib/apk/db/installed` | No | `syft for bomly-lite` |
+
+## How To Read This
+
+- Bomly tries detector chains from left to right.
+- Evidence patterns are files or paths Bomly uses during planning.
+- Install-first support means `--install-first` can run the ecosystem's normal install command before graph resolution.
+- Syft-backed entries provide broad compatibility, especially for containers and ecosystems without native Bomly graph resolution.

docs/detectors/ecosystems/conda.md

@@ -0,0 +1,16 @@
+# Conda Detectors
+
+<!-- Auto-generated by make generate. Do not edit manually. -->
+
+Bomly uses these detector chains when it finds `conda` package-manager evidence.
+
+| Package manager | Detector chain | Evidence patterns | Install-first support | Native command hints |
+| --- | --- | --- | --- | --- |
+| `conda` | `syft-detector` | `conda-meta/*.json` | No | `syft for bomly-lite` |
+
+## How To Read This
+
+- Bomly tries detector chains from left to right.
+- Evidence patterns are files or paths Bomly uses during planning.
+- Install-first support means `--install-first` can run the ecosystem's normal install command before graph resolution.
+- Syft-backed entries provide broad compatibility, especially for containers and ecosystems without native Bomly graph resolution.