# arafaykhalid/web-discoverability-skill architecture

> Architecture diagram of the GitHub repository arafaykhalid/web-discoverability-skill, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/arafaykhalid/web-discoverability-skill
- Repository: https://github.com/arafaykhalid/web-discoverability-skill

## Overview

This repository is an agent skill and command-line toolkit for auditing web discoverability, not a system that changes rankings or guarantees indexing. The principal workflow captures a site’s served output, builds a snapshot and profile, selects applicable requirements, runs deterministic checks, and reports evidence-backed findings. Separate registry-maintenance and benchmark capabilities support that audit product. The graph follows documented workflows and indexed imports; several internal check and reporting details are represented at subsystem level because their implementations were not all excerpted.

Main entry points: [`tools/cli.ts`](https://github.com/arafaykhalid/web-discoverability-skill/blob/main/tools/cli.ts) (CLI commands), [`tools/lib/registry.ts`](https://github.com/arafaykhalid/web-discoverability-skill/blob/main/tools/lib/registry.ts) (Registry loading), [`tools/lib/report.ts`](https://github.com/arafaykhalid/web-discoverability-skill/blob/main/tools/lib/report.ts) (Audit and metrics reports), [`tools/lib/capture.ts`](https://github.com/arafaykhalid/web-discoverability-skill/blob/main/tools/lib/capture.ts) (Site capture)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_audit["Site audit"]
  node_cli["CLI commands<br/>[cli.ts]"]
  node_capture["Site capture<br/>[capture.ts]"]
  node_profile["Site profiling<br/>[profile.ts]"]
  node_snapshot["Site snapshot<br/>[snapshot.ts]"]
  node_selector["Requirement selection<br/>[select.ts]"]
end

subgraph group_checks["Discoverability checks"]
  node_engine["Check registry and runner<br/>[index.ts]"]
  node_checkmodules["Domain check modules"]
  node_support["Check support<br/>[check-support.ts]"]
  node_html["HTML inspection<br/>[html.ts]"]
end

subgraph group_registry["Requirements registry"]
  node_requirements[("Requirement records")]
  node_model["Registry vocabulary<br/>[model.ts]"]
  node_registryloader["Registry loading<br/>[registry.ts]"]
  node_validator["Registry validation<br/>[validate.ts]"]
end

subgraph group_ops["Reports and benchmarks"]
  node_report["Audit and metrics reports<br/>[report.ts]"]
  node_docs["Registry documentation<br/>[docs.ts]"]
  node_bench["Check benchmarks<br/>[bench.ts]"]
  node_version["Freshness check<br/>[version.ts]"]
end

node_user(("Engineer or agent"))
node_site(("Target website"))

node_user -->|"runs commands"| node_cli
node_cli -->|"captures site"| node_capture
node_capture -->|"fetches responses"| node_site
node_cli -->|"loads snapshot"| node_snapshot
node_snapshot -->|"scans project"| node_profile
node_cli -->|"selects requirements"| node_selector
node_cli -->|"runs audit checks"| node_engine
node_engine -->|"loads checks"| node_checkmodules
node_checkmodules -->|"uses shared helpers"| node_support
node_support -->|"parses HTML"| node_html
node_cli -->|"loads records"| node_registryloader
node_registryloader -->|"reads records"| node_requirements
node_registryloader -->|"uses vocabulary"| node_model
node_cli -->|"validates registry"| node_validator
node_cli -->|"creates reports"| node_report
node_report -->|"validates records"| node_validator
node_report -->|"counts selections"| node_selector
node_cli -->|"generates docs"| node_docs
node_docs -->|"reads requirement corpus"| node_requirements
node_cli -->|"runs benchmarks"| node_bench
node_cli -->|"checks freshness"| node_version

click node_cli "https://github.com/arafaykhalid/web-discoverability-skill/blob/main/tools/cli.ts"
click node_capture "https://github.com/arafaykhalid/web-discoverability-skill/blob/main/tools/lib/capture.ts"
click node_profile "https://github.com/arafaykhalid/web-discoverability-skill/blob/main/tools/lib/profile.ts"
click node_snapshot "https://github.com/arafaykhalid/web-discoverability-skill/blob/main/tools/lib/snapshot.ts"
click node_selector "https://github.com/arafaykhalid/web-discoverability-skill/blob/main/tools/lib/select.ts"
click node_engine "https://github.com/arafaykhalid/web-discoverability-skill/blob/main/tools/lib/checks/index.ts"
click node_checkmodules "https://github.com/arafaykhalid/web-discoverability-skill/tree/main/tools/lib/checks"
click node_support "https://github.com/arafaykhalid/web-discoverability-skill/blob/main/tools/lib/check-support.ts"
click node_html "https://github.com/arafaykhalid/web-discoverability-skill/blob/main/tools/lib/html.ts"
click node_requirements "https://github.com/arafaykhalid/web-discoverability-skill/tree/main/requirements"
click node_model "https://github.com/arafaykhalid/web-discoverability-skill/blob/main/tools/lib/model.ts"
click node_registryloader "https://github.com/arafaykhalid/web-discoverability-skill/blob/main/tools/lib/registry.ts"
click node_validator "https://github.com/arafaykhalid/web-discoverability-skill/blob/main/tools/lib/validate.ts"
click node_report "https://github.com/arafaykhalid/web-discoverability-skill/blob/main/tools/lib/report.ts"
click node_docs "https://github.com/arafaykhalid/web-discoverability-skill/blob/main/tools/lib/docs.ts"
click node_bench "https://github.com/arafaykhalid/web-discoverability-skill/blob/main/tools/lib/bench.ts"
click node_version "https://github.com/arafaykhalid/web-discoverability-skill/blob/main/tools/lib/version.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_capture,node_profile,node_snapshot,node_selector toneBlue
class node_engine,node_checkmodules,node_support,node_html toneAmber
class node_requirements,node_model,node_registryloader,node_validator toneMint
class node_report,node_docs,node_bench,node_version toneRose
class node_user,node_site toneIndigo
```

## Components

### Site audit

- [CLI commands](https://github.com/arafaykhalid/web-discoverability-skill/blob/main/tools/cli.ts): `tools/cli.ts`
- [Site capture](https://github.com/arafaykhalid/web-discoverability-skill/blob/main/tools/lib/capture.ts): `tools/lib/capture.ts`
- [Site profiling](https://github.com/arafaykhalid/web-discoverability-skill/blob/main/tools/lib/profile.ts): `tools/lib/profile.ts`
- [Site snapshot](https://github.com/arafaykhalid/web-discoverability-skill/blob/main/tools/lib/snapshot.ts): `tools/lib/snapshot.ts`
- [Requirement selection](https://github.com/arafaykhalid/web-discoverability-skill/blob/main/tools/lib/select.ts): `tools/lib/select.ts`

### Discoverability checks

- [Check registry and runner](https://github.com/arafaykhalid/web-discoverability-skill/blob/main/tools/lib/checks/index.ts): `tools/lib/checks/index.ts`
- [Domain check modules](https://github.com/arafaykhalid/web-discoverability-skill/tree/main/tools/lib/checks): `tools/lib/checks`
- [Check support](https://github.com/arafaykhalid/web-discoverability-skill/blob/main/tools/lib/check-support.ts): `tools/lib/check-support.ts`
- [HTML inspection](https://github.com/arafaykhalid/web-discoverability-skill/blob/main/tools/lib/html.ts): `tools/lib/html.ts`

### Requirements registry

- [Requirement records](https://github.com/arafaykhalid/web-discoverability-skill/tree/main/requirements): `requirements`
- [Registry vocabulary](https://github.com/arafaykhalid/web-discoverability-skill/blob/main/tools/lib/model.ts): `tools/lib/model.ts`
- [Registry loading](https://github.com/arafaykhalid/web-discoverability-skill/blob/main/tools/lib/registry.ts): `tools/lib/registry.ts`
- [Registry validation](https://github.com/arafaykhalid/web-discoverability-skill/blob/main/tools/lib/validate.ts): `tools/lib/validate.ts`

### Reports and benchmarks

- [Audit and metrics reports](https://github.com/arafaykhalid/web-discoverability-skill/blob/main/tools/lib/report.ts): `tools/lib/report.ts`
- [Registry documentation](https://github.com/arafaykhalid/web-discoverability-skill/blob/main/tools/lib/docs.ts): `tools/lib/docs.ts`
- [Check benchmarks](https://github.com/arafaykhalid/web-discoverability-skill/blob/main/tools/lib/bench.ts): `tools/lib/bench.ts`
- [Freshness check](https://github.com/arafaykhalid/web-discoverability-skill/blob/main/tools/lib/version.ts): `tools/lib/version.ts`

### Other components

- **Engineer or agent**
- **Target website**

## Connections

- Engineer or agent → CLI commands: runs commands (evidence: `README.md`)
- CLI commands → Site capture: captures site (evidence: `tools/cli.ts`)
- Site capture → Target website: fetches responses (evidence: `README.md`)
- CLI commands → Site snapshot: loads snapshot (evidence: `tools/cli.ts`)
- Site snapshot → Site profiling: scans project (evidence: `tools/lib/snapshot.ts`)
- CLI commands → Requirement selection: selects requirements (evidence: `tools/cli.ts`)
- CLI commands → Check registry and runner: runs audit checks (evidence: `README.md`)
- Check registry and runner → Domain check modules: loads checks (evidence: `tools/lib/checks/index.ts`)
- Domain check modules → Check support: uses shared helpers (evidence: `tools/lib/checks/robots.ts`)
- Check support → HTML inspection: parses HTML (evidence: `tools/lib/check-support.ts`)
- CLI commands → Registry loading: loads records (evidence: `tools/cli.ts`)
- Registry loading → Requirement records: reads records (evidence: `tools/lib/registry.ts`)
- Registry loading → Registry vocabulary: uses vocabulary (evidence: `tools/lib/registry.ts`)
- CLI commands → Registry validation: validates registry (evidence: `tools/cli.ts`)
- CLI commands → Audit and metrics reports: creates reports (evidence: `tools/cli.ts`)
- Audit and metrics reports → Registry validation: validates records (evidence: `tools/lib/report.ts`)
- Audit and metrics reports → Requirement selection: counts selections (evidence: `tools/lib/report.ts`)
- CLI commands → Registry documentation: generates docs (evidence: `tools/cli.ts`)
- Registry documentation → Requirement records: reads requirement corpus (evidence: `tools/lib/docs.ts`)
- CLI commands → Check benchmarks: runs benchmarks (evidence: `tools/cli.ts`)
- CLI commands → Freshness check: checks freshness (evidence: `README.md`)
