docs: restructure the documentation, once again (#20)

Author: julio-rocketchat

.gitignore

@@ -2,3 +2,6 @@ node_modules/
 .env
 data/
 coverage/
+website/node_modules/
+website/.docusaurus/
+website/build/

CLAUDE.md

@@ -51,29 +51,29 @@ DEBUG_MODE               # set to "true" for verbose logging
 
 Two separate Node.js processes:
 
-**`src/server.js` — Webhook receiver**
+**`src/server.js` - Webhook receiver**
 - Express app with `POST /webhook`, `GET /health`, `GET /metrics` (when enabled), `GET /assets/layne-logo.png`
 - Verifies GitHub HMAC signature before processing
 - Handles two event types: `pull_request` and `workflow_run`
 - **`pull_request` trigger (default):** on opened/synchronize/reopened, creates a Check Run in `queued` state, enqueues a BullMQ job, returns 200
 - **`workflow_run` trigger:** on `pull_request` events, caches PR metadata in Redis (TTL 7 days) and creates a `skipped` Check Run; on `workflow_run completed` events matching the configured workflow name and conclusion, looks up cached PR metadata (falls back to GitHub API if cache is cold) then enqueues the scan
-- Job ID is deduplicated by `{repo}#{pr}@{sha}` — duplicate webhook deliveries are no-ops (Redis lock + queue check)
+- Job ID is deduplicated by `{repo}#{pr}@{sha}` - duplicate webhook deliveries are no-ops (Redis lock + queue check)
 - Exported `app` and `processWebhookRequest` for use in tests
 
-**`src/worker.js` — Job processor**
+**`src/worker.js` - Job processor**
 - BullMQ `Worker` consuming the `scans` queue with concurrency 5
 - `processJob()` is exported for direct testing without Redis
 - Per-job 10-minute timeout via `Promise.race`
-- Graceful shutdown on SIGTERM/SIGINT — finishes in-flight jobs before exiting
+- Graceful shutdown on SIGTERM/SIGINT - finishes in-flight jobs before exiting
 - When `METRICS_ENABLED=true`: starts an HTTP metrics server on `METRICS_PORT` and polls BullMQ queue counts every 15 s
 
 **Job lifecycle (inside `runScan`):**
 1. Mark Check Run `in_progress`
 2. Authenticate as installation via `src/auth.js` → short-lived token
 3. Create temp workspace (`src/fetcher.js` → `createWorkspace`)
-4. Partial-clone both head and base SHAs with `--filter=blob:none` — fetches trees/commits only, no blobs yet (`src/fetcher.js` → `setupRepo`)
+4. Partial-clone both head and base SHAs with `--filter=blob:none` - fetches trees/commits only, no blobs yet (`src/fetcher.js` → `setupRepo`)
 5. Diff the two commits via tree objects to get changed file paths (`getChangedFiles`)
-6. Sparse-checkout only the changed files — blobs fetched on demand (`checkoutFiles`)
+6. Sparse-checkout only the changed files - blobs fetched on demand (`checkoutFiles`)
 7. Load per-repo config via `src/config.js` → `loadScanConfig`
 8. Run scanners in parallel via `src/dispatcher.js` → `dispatch()`
 9. Convert findings to annotations via `src/reporter.js` → `buildAnnotations()`
@@ -83,11 +83,11 @@ Two separate Node.js processes:
 13. Clean up workspace in `finally`
 
 **Scanners (`src/adapters/`):**
-- `semgrep.js` — runs `semgrep scan --config auto --json`; exit code 1 = findings found (not an error); maps ERROR→high, WARNING→medium, INFO→low
-- `trufflehog.js` — runs `trufflehog filesystem --json --no-update`; exit code 183 = secrets found (not an error); batched at 200 files to stay under ARG_MAX; all findings are severity `high`
-- `claude.js` — calls the Anthropic API to detect malicious intent; **disabled by default**, opt in per repo; skips binary files; caps files at 50 KB; batches at 100 KB per API call; errors are caught and logged without failing the scan. Supports two modes (configured per-repo in `config/layne.json`):
+- `semgrep.js` - runs `semgrep scan --config auto --json`; exit code 1 = findings found (not an error); maps ERROR→high, WARNING→medium, INFO→low
+- `trufflehog.js` - runs `trufflehog filesystem --json --no-update`; exit code 183 = secrets found (not an error); batched at 200 files to stay under ARG_MAX; all findings are severity `high`
+- `claude.js` - calls the Anthropic API to detect malicious intent; **disabled by default**, opt in per repo; skips binary files; caps files at 50 KB; batches at 100 KB per API call; errors are caught and logged without failing the scan. Supports two modes (configured per-repo in `config/layne.json`):
   - **Prompt mode** (default): single `messages.create` call with a system prompt; use `claude.prompt` to override
-  - **Skill mode**: uses the Anthropic [API Skills beta](https://platform.claude.com/docs/en/build-with-claude/skills-guide) — adds a `code_execution` tool + an uploaded skill to each batch call, enabling runtime decoding, registry lookups, and richer static analysis; set `claude.skill: { id, version }` to enable; handles `pause_turn` continuations automatically (up to 10 turns per batch)
+  - **Skill mode**: uses the Anthropic [API Skills beta](https://platform.claude.com/docs/en/build-with-claude/skills-guide) - adds a `code_execution` tool + an uploaded skill to each batch call, enabling runtime decoding, registry lookups, and richer static analysis; set `claude.skill: { id, version }` to enable; handles `pause_turn` continuations automatically (up to 10 turns per batch)
 
 **Common finding shape:**
 ```js
@@ -118,32 +118,32 @@ Two separate Node.js processes:
 See [docs/2-configuration.md](docs/2-configuration.md) for the full schema and examples.
 
 Key points for code navigation:
-- Read once per process startup — **restart both server and worker to pick up changes**
+- Read once per process startup - **restart both server and worker to pick up changes**
 - Loaded and merged by `src/config.js` → `loadScanConfig`
 - Supports `$global` key for defaults inherited by all repos
 - Scanner blocks: per-repo spread over defaults (`{ ...DEFAULT_CONFIG.semgrep, ...repoOverrides.semgrep }`)
-- `trigger`: controls when scanning fires — `pull_request` (default, immediate) or `workflow_run` (deferred until a named CI workflow completes); global default → per-repo override
+- `trigger`: controls when scanning fires - `pull_request` (default, immediate) or `workflow_run` (deferred until a named CI workflow completes); global default → per-repo override
 - `notifications` and `labels`: per-repo notifier/key wins over global; per-repo absence = inherit global entirely
 - `extraArgs` fully replaces the default (not extended)
 - `config/layne.json` must be present in the Docker image (`COPY config/ ./config/`)
-- Notifier contract: `async function notify({ findings, owner, repo, prNumber, toolConfig })` — must never throw
+- Notifier contract: `async function notify({ findings, owner, repo, prNumber, toolConfig })` - must never throw
 - Notification dedup key: `layne:scan:count:{owner}/{repo}#{prNumber}` (Redis, 30-day TTL)
 - `webhookUrl` values starting with `$` are resolved from `process.env` at runtime
 - Label errors never affect the scan result or Check Run
 
 ## Metrics
 
 - `src/metrics.js` exports real prom-client objects when `METRICS_ENABLED=true`, silent no-op stubs otherwise
-- No `if (METRICS_ENABLED)` guards needed at call sites — stubs absorb all calls
+- No `if (METRICS_ENABLED)` guards needed at call sites - stubs absorb all calls
 - Worker: metrics HTTP server + BullMQ queue poller (15 s interval) started only when enabled
 - Server: `GET /metrics` route registered only when enabled
 - `monitoring/` directory has Prometheus scrape config and a pre-built Grafana dashboard
 
 ## Testing conventions
 
 - Tests use Vitest with ESM (`"type": "module"` in package.json)
-- `src/__tests__/setup.js` sets all required env vars before each test file; `ANTHROPIC_API_KEY` and `METRICS_ENABLED` are intentionally not set — adapters and metrics are mocked
-- External dependencies (`@octokit/auth-app`, `@octokit/rest`, `bullmq`, `ioredis`, `@anthropic-ai/sdk`, `prom-client`) are always mocked — no live connections in tests
+- `src/__tests__/setup.js` sets all required env vars before each test file; `ANTHROPIC_API_KEY` and `METRICS_ENABLED` are intentionally not set - adapters and metrics are mocked
+- External dependencies (`@octokit/auth-app`, `@octokit/rest`, `bullmq`, `ioredis`, `@anthropic-ai/sdk`, `prom-client`) are always mocked - no live connections in tests
 - `src/metrics.js` is mocked in worker and server tests with `vi.fn()` stubs; tested in isolation in `src/__tests__/metrics.test.js`
 - `processJob` and `dispatch` are exported specifically for unit testing without live infrastructure
 - Tests import modules with `await import(...)` after `vi.mock()` calls to handle ESM module caching

CONTRIBUTING.md

@@ -34,7 +34,7 @@ Thanks for your interest in contributing. This document covers the branch model,
 
 ## Changesets
 
-Every PR that changes behaviour needs a changeset — a small file that describes what changed and what kind of version bump it warrants. The changeset check CI will fail if one is missing.
+Every PR that changes behaviour needs a changeset - a small file that describes what changed and what kind of version bump it warrants. The changeset check CI will fail if one is missing.
 
 **Add a changeset:**
 ```bash
@@ -53,7 +53,7 @@ This prompts you to pick a bump type and write a one-line description, then writ
 
 **Skipping the changeset:**
 
-For PRs that don't warrant a release entry — CI fixes, typos, documentation updates — add the `no-changeset` label to the PR. The check will be skipped.
+For PRs that don't warrant a release entry - CI fixes, typos, documentation updates - add the `no-changeset` label to the PR. The check will be skipped.
 
 ---
 
@@ -62,7 +62,7 @@ For PRs that don't warrant a release entry — CI fixes, typos, documentation up
 - **One thing per PR.** If you find yourself writing "and also..." in the description, split it.
 - **Explain the why.** The diff shows what changed. The description should say why.
 - **Every behaviour change needs a test.** If you're fixing a bug, the test should fail on the old code.
-- **Security-sensitive areas get extra scrutiny** — webhook verification, auth, file path handling, scanner output parsing. Explain your threat model.
+- **Security-sensitive areas get extra scrutiny** - webhook verification, auth, file path handling, scanner output parsing. Explain your threat model.
 
 **Example description:**
 
@@ -98,8 +98,8 @@ All four must pass before a PR can be merged.
 
 ## Extending Layne
 
-- **Adding a new scanner:** see [docs/6-extending.md — Adding a New Scanner](docs/6-extending.md#adding-a-new-scanner)
-- **Adding a notification provider:** see [docs/6-extending.md — Adding a New Notifier](docs/6-extending.md#adding-a-new-notifier)
+- **Adding a new scanner:** see [docs/6-extending.md - Adding a New Scanner](docs/6-extending.md#adding-a-new-scanner)
+- **Adding a notification provider:** see [docs/6-extending.md - Adding a New Notifier](docs/6-extending.md#adding-a-new-notifier)
 
 ---
 

README.md

@@ -52,7 +52,7 @@ Layne ships with three built-in scanners. You can enable, disable, or configure
 | [Trufflehog](https://github.com/trufflesecurity/trufflehog) | Secrets, API keys and credentials | Runs `trufflehog filesystem`; use `--only-verified` to reduce noise |
 | [Claude](https://www.anthropic.com) | Bugs, vulnerabilities, backdoors, obfuscated payloads, supply-chain attacks (you can define a system prompt or a skill to use) | Disabled by default; opt in per repo; requires `ANTHROPIC_API_KEY` |
 
-You can also add your own scanners. See [Extending Layne](docs/6-extending.md).
+You can also add your own scanners. See [Extending Layne](website/docs/extending.md).
 
 ### Layne's Workflow
 
@@ -74,13 +74,15 @@ And you can configure Layne to send a notification via webhook to a Rocket.Chat
 
 ## Documentation
 
-- [**Deployment**](docs/1-deployment.md) - EC2 setup, Docker Compose, TLS, and automated CI/CD pipeline
-- [**Configuration**](docs/2-configuration.md) - per-repo scanner settings, PR labels, and chat notifications
-- [**Local Development**](docs/3-local-development.md) - set up a local dev environment, replay webhooks, and debug without deploying
-- [**Security Architecture**](docs/4-security-architecture.md) - permissions, credential handling, network exposure, and compromise scenarios
-- [**Metrics**](docs/5-metrics.md) - Prometheus metrics and the bundled Grafana dashboard
-- [**Extending Layne**](docs/6-extending.md) - adding new scanners and notification providers
-- [**Reference**](docs/7-reference.md) - environment variables, finding shape, severity levels, and queue behaviour
+Run the documentation site locally:
+
+```bash
+npm run docs:dev
+```
+
+Then open [http://localhost:3000](http://localhost:3000).
+
+The full documentation covers deployment, configuration, scanners, notifiers, PR comments, finding suppression, metrics, security architecture, and more.
 
 ## License
 

SECURITY.md

@@ -4,7 +4,7 @@
 
 If you believe you have found a security vulnerability in Layne, please do not open a public GitHub issue. Instead, report it through one of the following channels:
 
-- **GitHub Security Advisory:** [Report a vulnerability](../../security/advisories/new) — opens a private advisory draft visible only to maintainers.
+- **GitHub Security Advisory:** [Report a vulnerability](../../security/advisories/new) - opens a private advisory draft visible only to maintainers.
 - **Email:** [security@rocket.chat](mailto:security@rocket.chat)
 
 Please include as much detail as possible: a description of the vulnerability, steps to reproduce it, and the potential impact. If you have a proof-of-concept or suggested fix, we welcome that too.
@@ -19,7 +19,7 @@ We ask that you:
 
 - Give us reasonable time to investigate and fix the issue before disclosing it publicly.
 - Avoid accessing, modifying, or deleting data that does not belong to you.
-- Act in good faith — we will do the same.
+- Act in good faith - we will do the same.
 
 Researchers who follow these guidelines will be credited in the fix unless they prefer to remain anonymous.