seo-crawl-audit 0.7.1 → 0.8.0

package/README.md

@@ -10,6 +10,33 @@ results stay in local JSON, checkpoint, CSV, and self-contained HTML files.
 [Open the interactive example report](https://melnixdev.github.io/seo-crawl-audit/)
 or [view its source file](examples/quotes-toscrape-report.html).
 
+## Report preview
+
+The report is a self-contained HTML file: open it locally, share it as an
+artifact, or publish the same file on GitHub Pages. Charts and filters work
+without a server.
+
+### Overview and local history
+
+![SEO Crawl Audit summary cards and local scan history](https://raw.githubusercontent.com/MelnixDev/seo-crawl-audit/main/docs/images/report-overview.png)
+
+The overview keeps scan coverage, issue counts, and locally stored trends in
+one place.
+
+### Interactive issue analytics
+
+![SEO Crawl Audit interactive issue statistics](https://raw.githubusercontent.com/MelnixDev/seo-crawl-audit/main/docs/images/report-analytics.png)
+
+Select a severity, rule, lifecycle state, or page template to filter the issue
+table immediately.
+
+### Filtered issue table
+
+![SEO Crawl Audit issue table filtered to errors](https://raw.githubusercontent.com/MelnixDev/seo-crawl-audit/main/docs/images/report-issues.png)
+
+Chart selections and report filters narrow the table to the findings that need
+attention, with evidence and remediation kept alongside each issue.
+
 ## Highlights
 
 - automatic `robots.txt`, sitemap, sitemap-index, and gzip sitemap support;
@@ -26,8 +53,8 @@ or [view its source file](examples/quotes-toscrape-report.html).
   and local report branding;
 - interactive issue statistics for severity, frequent checks, ownership, and
   regression lifecycle, with chart-to-table filtering;
-- a production-versus-preview release guard with safe environment-based
-  authentication for private deployments;
+- safe environment-based authentication for private `doctor`, `scan`,
+  `check`, Action, and production-versus-preview workflows;
 - configuration, suppressions with expiry, severity overrides, and budgets;
 - a self-contained GitHub Action that runs inside the GitHub runner;
 - typed engine API with injectable `fetch`, checkpoints, events, logger, and
@@ -64,6 +91,43 @@ npm run build
 npm link --workspace seo-crawl-audit
 ```
 
+## Initialize a project
+
+Create a safe configuration in an existing project:
+
+```bash
+npx seo-crawl-audit init https://example.com/
+```
+
+The interactive setup can also create a manual, scheduled, or pull-request
+GitHub Actions workflow. For a site whose content is published outside pull
+requests, generate the scheduled workflow:
+
+```bash
+npx seo-crawl-audit init https://example.com/ \
+  --workflow scheduled \
+  --yes
+```
+
+Existing config and workflow files are never replaced without an explicit
+confirmation or `--force`. The generated `.gitignore` recommendations exclude
+runtime checkpoints, local history, and reports, but intentionally keep the
+optional `.seo-audit.json` regression baseline available for version control.
+
+[Read the complete initialization guide](https://github.com/MelnixDev/seo-crawl-audit/blob/main/docs/initialization.md).
+
+Verify the project setup without starting a full crawl:
+
+```bash
+seo-audit doctor
+seo-audit doctor --offline
+```
+
+[Read the project diagnostics guide](https://github.com/MelnixDev/seo-crawl-audit/blob/main/docs/doctor.md).
+
+Protected preview or staging site credentials can be supplied through a named
+JSON environment variable. [Read the authenticated scans guide](https://github.com/MelnixDev/seo-crawl-audit/blob/main/docs/authenticated-scans.md).
+
 ## Five-minute example
 
 [Quotes to Scrape](https://quotes.toscrape.com/) is a public educational site
@@ -89,6 +153,32 @@ seo-audit check https://quotes.toscrape.com/ \
 
 ## Commands
 
+### `seo-audit init [url]`
+
+Creates `seo-audit.config.json`, adds safe local artifact recommendations to
+`.gitignore`, and can create an optional GitHub Actions workflow.
+
+```bash
+seo-audit init https://example.com/
+seo-audit init https://example.com/ --workflow manual --yes
+seo-audit init https://example.com/ --workflow scheduled --yes
+seo-audit init https://example.com/ --workflow pull-request --yes
+```
+
+Workflow modes are `none`, `manual`, `scheduled`, and `pull-request`.
+
+### `seo-audit doctor [url]`
+
+Checks the local Node.js runtime, configuration, output access, start page,
+robots.txt, and sitemap without crawling linked HTML pages. Node.js is required
+only on the machine running the CLI; the audited site can use any server stack.
+
+```bash
+seo-audit doctor
+seo-audit doctor https://example.com/
+seo-audit doctor --offline --json
+```
+
 ### `seo-audit <url>`
 
 Shortcut for `seo-audit scan <url>`.
@@ -108,6 +198,14 @@ seo-audit scan https://example.com/ --pages 250
 seo-audit scan https://example.com/ --all
 ```
 
+For a protected site, keep headers outside command history and project files:
+
+```bash
+export SEO_AUDIT_SITE_HEADERS='{"Authorization":"Bearer …"}'
+seo-audit scan https://preview.example.com/ \
+  --headers-env SEO_AUDIT_SITE_HEADERS
+```
+
 When a sitemap is found in an interactive terminal, the menu offers the first
 100 pages, every sitemap URL, groups of 100 with confirmation, or a custom
 number. `--pages` and `--all` skip the menu. If no sitemap is found, press Enter
@@ -204,6 +302,7 @@ seo-audit history \
 --include-query         Treat query-string URLs as separate pages
 --ignore-robots         Ignore robots.txt disallow rules
 --strict                Fail check on warnings as well as errors
+--headers-env <name>    Read target headers from a JSON environment variable
 --production <url>      Production URL for compare
 --preview <url>         Preview deployment URL for compare
 --production-headers-env <name>
@@ -214,6 +313,11 @@ seo-audit history \
 --no-history            Do not save this scan to local history
 --from <snapshot>       Older snapshot for an explicit history comparison
 --to <snapshot>         Newer snapshot for an explicit history comparison
+--directory <path>      Project directory for init
+--workflow <mode>       Init workflow: none, manual, scheduled, or pull-request
+--yes                   Accept safe init defaults without prompting
+--force                 Allow init to replace existing generated files
+--offline               Skip doctor network checks
 --json                  Print machine-readable output
 --help                  Show help
 --version               Show the installed version
@@ -370,7 +474,7 @@ jobs:
             ${{ steps.seo.outputs.summary }}
 ```
 
-[Read all Action inputs and outputs](docs/github-action.md).
+[Read all Action inputs, outputs, and generated workflow modes](https://github.com/MelnixDev/seo-crawl-audit/blob/main/docs/github-action.md).
 
 ## Core API and repository structure
 
@@ -382,6 +486,11 @@ packages/cli     seo-crawl-audit       — terminal UX and npm executable
 packages/action  @seo-crawl-audit/action — GitHub runner entry point
 ```
 
+`@seo-crawl-audit/core` is currently an internal workspace package and is not
+published separately on npm. Install `seo-crawl-audit` for the supported,
+self-contained CLI. The imports below document the repository API used by the
+CLI and Action and are intended for contributors working in this workspace.
+
 ```ts
 import { audit, planScan, scan } from "@seo-crawl-audit/core";
 import { createFileCheckpointStore } from "@seo-crawl-audit/core/node";
@@ -443,6 +552,9 @@ CI covers Node.js 20, 22, and 24. Tests use local HTTP fixtures for robots,
 sitemaps, gzip, retries, redirects, cancellation, checkpoint resume, migration,
 rules, lifecycle, HTML escaping, npm packaging, and the GitHub Action.
 
+Maintainers publish the CLI through token-free
+[npm trusted publishing](https://github.com/MelnixDev/seo-crawl-audit/blob/main/docs/publishing.md).
+
 ## License
 
 MIT