jekyll-agent-audit 0.1.0

data/doc/Jekyll/AgentAudit/Rules/Provenance.md

@@ -0,0 +1,127 @@
+# Module Jekyll::AgentAudit::Rules::Provenance <a id="module-Jekyll-AgentAudit-Rules-Provenance"></a>
+
+|  |  |
+| --- | --- |
+| **Defined in** | lib/jekyll/agent_audit/rules/provenance.rb |
+
+## Constants
+### `ARTICLE_TYPES` <a id="constant-ARTICLE_TYPES"></a> <a id="ARTICLE_TYPES-constant"></a>
+Not documented.
+
+### `INTENT_KEYS` <a id="constant-INTENT_KEYS"></a> <a id="INTENT_KEYS-constant"></a>
+Not documented.
+
+## Public Class Methods
+### `ambiguous_article?(document, context)` <a id="method-c-ambiguous_article-3F"></a> <a id="ambiguous_article?-class_method"></a>
+- **@return** [Boolean]
+
+### `article?(node)` <a id="method-c-article-3F"></a> <a id="article?-class_method"></a>
+- **@return** [Boolean]
+
+### `author_identity_kind(value)` <a id="method-c-author_identity_kind"></a> <a id="author_identity_kind-class_method"></a>
+Not documented.
+
+### `author_set(value)` <a id="method-c-author_set"></a> <a id="author_set-class_method"></a>
+Not documented.
+
+### `author_sources(document, context)` <a id="method-c-author_sources"></a> <a id="author_sources-class_method"></a>
+Not documented.
+
+### `canonical_urls(document, context)` <a id="method-c-canonical_urls"></a> <a id="canonical_urls-class_method"></a>
+Not documented.
+
+### `collect_nodes(value, result, line_number = nil)` <a id="method-c-collect_nodes"></a> <a id="collect_nodes-class_method"></a>
+Not documented.
+
+### `comparable_date(values, context)` <a id="method-c-comparable_date"></a> <a id="comparable_date-class_method"></a>
+Not documented.
+
+### `date_order(document, context)` <a id="method-c-date_order"></a> <a id="date_order-class_method"></a>
+Not documented.
+
+### `disjoint?(a, b)` <a id="method-c-disjoint-3F"></a> <a id="disjoint?-class_method"></a>
+- **@return** [Boolean]
+
+### `draft(document, message, observation, line = nil, related_locations = [])` <a id="method-c-draft"></a> <a id="draft-class_method"></a>
+Not documented.
+
+### `evaluate(id, document, context)` <a id="method-c-evaluate"></a> <a id="evaluate-class_method"></a>
+Not documented.
+
+### `explicit_sources(document, field)` <a id="method-c-explicit_sources"></a> <a id="explicit_sources-class_method"></a>
+Not documented.
+
+### `infer_seo_rendered_fallback!(values, document, context)` <a id="method-c-infer_seo_rendered_fallback-21"></a> <a id="infer_seo_rendered_fallback!-class_method"></a>
+Not documented.
+
+### `intent_value(data, field)` <a id="method-c-intent_value"></a> <a id="intent_value-class_method"></a>
+Not documented.
+
+### `interval_before?(a, b)` <a id="method-c-interval_before-3F"></a> <a id="interval_before?-class_method"></a>
+- **@return** [Boolean]
+
+### `invalid_dates(document, context)` <a id="method-c-invalid_dates"></a> <a id="invalid_dates-class_method"></a>
+Not documented.
+
+### `invalid_jsonld(document)` <a id="method-c-invalid_jsonld"></a> <a id="invalid_jsonld-class_method"></a>
+Not documented.
+
+### `jsonld_nodes(document)` <a id="method-c-jsonld_nodes"></a> <a id="jsonld_nodes-class_method"></a>
+Not documented.
+
+### `line(script)` <a id="method-c-line"></a> <a id="line-class_method"></a>
+Not documented.
+
+### `locations_for(sources)` <a id="method-c-locations_for"></a> <a id="locations_for-class_method"></a>
+Not documented.
+
+### `metadata_comparable?(document, context)` <a id="method-c-metadata_comparable-3F"></a> <a id="metadata_comparable?-class_method"></a>
+- **@return** [Boolean]
+
+### `metadata_conflict(document, context)` <a id="method-c-metadata_conflict"></a> <a id="metadata_conflict-class_method"></a>
+Not documented.
+
+### `metadata_sources(document, field)` <a id="method-c-metadata_sources"></a> <a id="metadata_sources-class_method"></a>
+Not documented.
+
+### `normalize_name(value)` <a id="method-c-normalize_name"></a> <a id="normalize_name-class_method"></a>
+Not documented.
+
+### `overlaps?(a, b)` <a id="method-c-overlaps-3F"></a> <a id="overlaps?-class_method"></a>
+- **@return** [Boolean]
+
+### `parse_date(value, context)` <a id="method-c-parse_date"></a> <a id="parse_date-class_method"></a>
+Not documented.
+
+### `primary_article(document, context)` <a id="method-c-primary_article"></a> <a id="primary_article-class_method"></a>
+Not documented.
+
+### `provenance_sources(document, context)` <a id="method-c-provenance_sources"></a> <a id="provenance_sources-class_method"></a>
+Not documented.
+
+### `publisher_sources(document, context)` <a id="method-c-publisher_sources"></a> <a id="publisher_sources-class_method"></a>
+Not documented.
+
+### `resolved_value(value, document, context)` <a id="method-c-resolved_value"></a> <a id="resolved_value-class_method"></a>
+Not documented.
+
+### `scripts(document)` <a id="method-c-scripts"></a> <a id="scripts-class_method"></a>
+Not documented.
+
+### `seo_fallback_date?(graph, document, context)` <a id="method-c-seo_fallback_date-3F"></a> <a id="seo_fallback_date?-class_method"></a>
+- **@return** [Boolean]
+
+### `seo_plugin_active?(context)` <a id="method-c-seo_plugin_active-3F"></a> <a id="seo_plugin_active?-class_method"></a>
+- **@return** [Boolean]
+
+### `source(value, origin, entity, line = nil)` <a id="method-c-source"></a> <a id="source-class_method"></a>
+Not documented.
+
+### `source_observation(source)` <a id="method-c-source_observation"></a> <a id="source_observation-class_method"></a>
+Not documented.
+
+### `timezone(context)` <a id="method-c-timezone"></a> <a id="timezone-class_method"></a>
+Not documented.
+
+### `timezone_free_timestamp?(value, context)` <a id="method-c-timezone_free_timestamp-3F"></a> <a id="timezone_free_timestamp?-class_method"></a>
+- **@return** [Boolean]

data/doc/Jekyll/AgentAudit/Rules/Publication.md

@@ -0,0 +1,73 @@
+# Module Jekyll::AgentAudit::Rules::Publication <a id="module-Jekyll-AgentAudit-Rules-Publication"></a>
+
+|  |  |
+| --- | --- |
+| **Defined in** | lib/jekyll/agent_audit/rules/publication.rb |
+
+## Constants
+### `IDS` <a id="constant-IDS"></a> <a id="IDS-constant"></a>
+Not documented.
+
+### `SEVERITIES` <a id="constant-SEVERITIES"></a> <a id="SEVERITIES-constant"></a>
+Not documented.
+
+## Public Class Methods
+### `architecture_orphan(document, context)` <a id="method-c-architecture_orphan"></a> <a id="architecture_orphan-class_method"></a>
+Not documented.
+
+### `architecture_output_collision(_document, context)` <a id="method-c-architecture_output_collision"></a> <a id="architecture_output_collision-class_method"></a>
+Not documented.
+
+### `asset_target?(entry)` <a id="method-c-asset_target-3F"></a> <a id="asset_target?-class_method"></a>
+- **@return** [Boolean]
+
+### `collision(context)` <a id="method-c-collision"></a> <a id="collision-class_method"></a>
+Not documented.
+
+### `evaluate(id, document, context)` <a id="method-c-evaluate"></a> <a id="evaluate-class_method"></a>
+Not documented.
+
+### `finding(rule, document, message, observation, line = nil, related_locations = [])` <a id="method-c-finding"></a> <a id="finding-class_method"></a>
+Not documented.
+
+### `graph(context)` <a id="method-c-graph"></a> <a id="graph-class_method"></a>
+Not documented.
+
+### `identity_canonical_invalid(document, _context)` <a id="method-c-identity_canonical_invalid"></a> <a id="identity_canonical_invalid-class_method"></a>
+Not documented.
+
+### `identity_canonical_multiple(document, context)` <a id="method-c-identity_canonical_multiple"></a> <a id="identity_canonical_multiple-class_method"></a>
+Not documented.
+
+### `identity_canonical_target_missing(document, context)` <a id="method-c-identity_canonical_target_missing"></a> <a id="identity_canonical_target_missing-class_method"></a>
+Not documented.
+
+### `links(document, context)` <a id="method-c-links"></a> <a id="links-class_method"></a>
+Not documented.
+
+### `links_fragment_missing(document, context)` <a id="method-c-links_fragment_missing"></a> <a id="links_fragment_missing-class_method"></a>
+Not documented.
+
+### `links_target_missing(document, context)` <a id="method-c-links_target_missing"></a> <a id="links_target_missing-class_method"></a>
+Not documented.
+
+### `root?(document, context)` <a id="method-c-root-3F"></a> <a id="root?-class_method"></a>
+- **@return** [Boolean]
+
+### `structure_h1_absent(document, _context)` <a id="method-c-structure_h1_absent"></a> <a id="structure_h1_absent-class_method"></a>
+Not documented.
+
+### `structure_heading_empty(document, _context)` <a id="method-c-structure_heading_empty"></a> <a id="structure_heading_empty-class_method"></a>
+Not documented.
+
+### `structure_heading_jump(document, _context)` <a id="method-c-structure_heading_jump"></a> <a id="structure_heading_jump-class_method"></a>
+Not documented.
+
+### `structure_id_duplicate(document, _context)` <a id="method-c-structure_id_duplicate"></a> <a id="structure_id_duplicate-class_method"></a>
+Not documented.
+
+### `structure_link_unnamed(document, _context)` <a id="method-c-structure_link_unnamed"></a> <a id="structure_link_unnamed-class_method"></a>
+Not documented.
+
+### `structure_title_missing(document, _context)` <a id="method-c-structure_title_missing"></a> <a id="structure_title_missing-class_method"></a>
+Not documented.

data/doc/Jekyll/AgentAudit/Rules.md

@@ -0,0 +1,5 @@
+# Module Jekyll::AgentAudit::Rules <a id="module-Jekyll-AgentAudit-Rules"></a>
+
+|  |  |
+| --- | --- |
+| **Defined in** | lib/jekyll/agent_audit/rules/provenance.rb, lib/jekyll/agent_audit/rules/publication.rb |

data/doc/Jekyll/AgentAudit/Runner.md

@@ -0,0 +1,13 @@
+# Class Jekyll::AgentAudit::Runner <a id="class-Jekyll-AgentAudit-Runner"></a>
+
+|  |  |
+| --- | --- |
+| **Inherits** | Object |
+| **Defined in** | lib/jekyll/agent_audit/runner.rb |
+
+## Public Instance Methods
+### `initialize(options = {})` <a id="method-i-initialize"></a> <a id="initialize-instance_method"></a>
+- **@return** [Runner] a new instance of Runner
+
+### `run()` <a id="method-i-run"></a> <a id="run-instance_method"></a>
+Not documented.

data/doc/Jekyll/AgentAudit/UrlResolver.md

@@ -0,0 +1,13 @@
+# Class Jekyll::AgentAudit::UrlResolver <a id="class-Jekyll-AgentAudit-UrlResolver"></a>
+
+|  |  |
+| --- | --- |
+| **Inherits** | Object |
+| **Defined in** | lib/jekyll/agent_audit/url_resolver.rb |
+
+## Public Instance Methods
+### `initialize(entries, site_config, configuration)` <a id="method-i-initialize"></a> <a id="initialize-instance_method"></a>
+- **@return** [UrlResolver] a new instance of UrlResolver
+
+### `resolve(href, document, base: = true)` <a id="method-i-resolve"></a> <a id="resolve-instance_method"></a>
+Not documented.

data/doc/Jekyll/AgentAudit.md

@@ -0,0 +1,35 @@
+# Module Jekyll::AgentAudit <a id="module-Jekyll-AgentAudit"></a>
+
+|  |  |
+| --- | --- |
+| **Defined in** | lib/jekyll/agent_audit/errors.rb, lib/jekyll/agent_audit/report.rb, lib/jekyll/agent_audit/runner.rb, lib/jekyll/agent_audit/finding.rb, lib/jekyll/agent_audit/version.rb, lib/jekyll/agent_audit/registry.rb, lib/jekyll/agent_audit/extractor.rb, lib/jekyll/agent_audit/link_graph.rb, lib/jekyll/agent_audit/url_resolver.rb, lib/jekyll/agent_audit/configuration.rb, lib/jekyll/agent_audit/reporters/json.rb, lib/jekyll/agent_audit/build_inventory.rb, lib/jekyll/agent_audit/rules/provenance.rb, lib/jekyll/agent_audit/reporters/console.rb, lib/jekyll/agent_audit/rules/publication.rb |
+
+## Constants
+### `VERSION` <a id="constant-VERSION"></a> <a id="VERSION-constant"></a>
+Not documented.
+
+# Documentation
+
+- [AgentAudit/BuildInventory.md](AgentAudit/BuildInventory.md)
+- [AgentAudit/Configuration.md](AgentAudit/Configuration.md)
+- [AgentAudit/ConfigurationError.md](AgentAudit/ConfigurationError.md)
+- [AgentAudit/Error.md](AgentAudit/Error.md)
+- [AgentAudit/Extractor.md](AgentAudit/Extractor.md)
+- [AgentAudit/Finding.md](AgentAudit/Finding.md)
+- [AgentAudit/InputError.md](AgentAudit/InputError.md)
+- [AgentAudit/LinkGraph.md](AgentAudit/LinkGraph.md)
+- [AgentAudit/Registry.md](AgentAudit/Registry.md)
+- [AgentAudit/Report.md](AgentAudit/Report.md)
+- [AgentAudit/ReportError.md](AgentAudit/ReportError.md)
+- [AgentAudit/Reporters/Console.md](AgentAudit/Reporters/Console.md)
+- [AgentAudit/Reporters/JSON.md](AgentAudit/Reporters/JSON.md)
+- [AgentAudit/Reporters.md](AgentAudit/Reporters.md)
+- [AgentAudit/Rules/Provenance.md](AgentAudit/Rules/Provenance.md)
+- [AgentAudit/Rules/Publication.md](AgentAudit/Rules/Publication.md)
+- [AgentAudit/Rules.md](AgentAudit/Rules.md)
+- [AgentAudit/Runner.md](AgentAudit/Runner.md)
+- [AgentAudit/UrlResolver.md](AgentAudit/UrlResolver.md)
+- [Commands/AgentAudit/CommandParser.md](Commands/AgentAudit/CommandParser.md)
+- [Commands/AgentAudit/ParserErrors.md](Commands/AgentAudit/ParserErrors.md)
+- [Commands/AgentAudit.md](Commands/AgentAudit.md)
+- [Commands.md](Commands.md)

data/doc/Jekyll/Commands/AgentAudit/CommandParser.md

@@ -0,0 +1,9 @@
+# Module Jekyll::Commands::AgentAudit::CommandParser <a id="module-Jekyll-Commands-AgentAudit-CommandParser"></a>
+
+|  |  |
+| --- | --- |
+| **Defined in** | lib/jekyll/agent_audit/command.rb |
+
+## Public Instance Methods
+### `go(arguments, parser, config)` <a id="method-i-go"></a> <a id="go-instance_method"></a>
+Not documented.

data/doc/Jekyll/Commands/AgentAudit/ParserErrors.md

@@ -0,0 +1,9 @@
+# Module Jekyll::Commands::AgentAudit::ParserErrors <a id="module-Jekyll-Commands-AgentAudit-ParserErrors"></a>
+
+|  |  |
+| --- | --- |
+| **Defined in** | lib/jekyll/agent_audit/command.rb |
+
+## Public Instance Methods
+### `parse!(*arguments)` <a id="method-i-parse-21"></a> <a id="parse!-instance_method"></a>
+Not documented.

data/doc/Jekyll/Commands/AgentAudit.md

@@ -0,0 +1,13 @@
+# Class Jekyll::Commands::AgentAudit <a id="class-Jekyll-Commands-AgentAudit"></a>
+
+|  |  |
+| --- | --- |
+| **Inherits** | Jekyll::Command |
+| **Defined in** | lib/jekyll/agent_audit/command.rb |
+
+## Public Class Methods
+### `init_with_program(prog)` <a id="method-c-init_with_program"></a> <a id="init_with_program-class_method"></a>
+Not documented.
+
+### `process(options)` <a id="method-c-process"></a> <a id="process-class_method"></a>
+Not documented.

data/doc/Jekyll/Commands.md

@@ -0,0 +1,5 @@
+# Module Jekyll::Commands <a id="module-Jekyll-Commands"></a>
+
+|  |  |
+| --- | --- |
+| **Defined in** | lib/jekyll/agent_audit/command.rb |

data/doc/Jekyll.md

@@ -0,0 +1,5 @@
+# Module Jekyll <a id="module-Jekyll"></a>
+
+|  |  |
+| --- | --- |
+| **Defined in** | lib/jekyll/agent_audit/errors.rb, lib/jekyll/agent_audit/report.rb, lib/jekyll/agent_audit/runner.rb, lib/jekyll/agent_audit/command.rb, lib/jekyll/agent_audit/finding.rb, lib/jekyll/agent_audit/version.rb, lib/jekyll/agent_audit/registry.rb, lib/jekyll/agent_audit/extractor.rb, lib/jekyll/agent_audit/link_graph.rb, lib/jekyll/agent_audit/url_resolver.rb, lib/jekyll/agent_audit/configuration.rb, lib/jekyll/agent_audit/reporters/json.rb, lib/jekyll/agent_audit/build_inventory.rb, lib/jekyll/agent_audit/rules/provenance.rb, lib/jekyll/agent_audit/reporters/console.rb, lib/jekyll/agent_audit/rules/publication.rb |

data/doc/README.md

@@ -0,0 +1,180 @@
+# jekyll-agent-audit
+
+An offline audit of rendered Jekyll publications. It finds broken local references, conflicting document identity, structural markup problems, and observable metadata contradictions. It does not predict search rankings or AI citations, score pages, rewrite content, or check deployed HTTP behavior.
+
+## Install and run
+
+Add the gem to your site's **Gemfile**, in the command-loading group:
+
+```ruby
+group :jekyll_plugins do
+  gem "jekyll-agent-audit", "~> 0.1.0"
+end
+```
+
+For an unpublished local checkout, add `path: "/path/to/jekyll-agent-audit"` to that declaration. Run `bundle install`, then:
+
+```sh
+bundle exec jekyll agent:audit
+bundle exec jekyll agent:audit --format json --output tmp/agent-audit.json
+bundle exec jekyll agent:audit --config _config.yml,_config.production.yml
+bundle exec jekyll agent:audit --fail-on warning
+bundle exec jekyll agent:audit --only links.target_missing,identity.canonical_multiple
+bundle exec jekyll agent:audit --list-rules --format json
+bundle exec jekyll agent:audit --explain identity.canonical_multiple
+```
+
+Putting the gem only under `_config.yml`'s `plugins` setting is too late for initial command discovery. See [Jekyll's command integration documentation](https://jekyllrb.com/docs/plugins/commands/).
+
+The command makes one full build in a temporary directory, with a separate temporary cache, and inspects the final output. Existing `_site` output is preserved. Build logs go to stderr; JSON stdout contains one report. `--output` writes atomically. Merely loading the gem does not audit an ordinary `jekyll build`.
+
+The analyzer performs no network requests. Your site's ordinary build plugins retain their own behavior, including any network requests or custom filesystem writes they perform. Temporary build isolation cannot constrain arbitrary third-party plugin side effects.
+
+## Findings and exit codes
+
+The default release enables these 17 rules:
+
+| Severity | Rules |
+| --- | --- |
+| Error | `architecture.output_collision`, `links.target_missing`, `links.fragment_missing`, `identity.canonical_invalid`, `identity.canonical_multiple`, `identity.canonical_target_missing`, `structure.id_duplicate`, `provenance.jsonld_invalid` |
+| Warning | `architecture.orphan`, `structure.title_missing`, `structure.heading_empty`, `structure.link_unnamed`, `provenance.date_invalid`, `provenance.date_order`, `provenance.metadata_conflict` |
+| Info | `structure.h1_absent`, `structure.heading_jump` |
+
+`--explain RULE` gives applicability, evidence, limitations, and remediation. Deferred catalog rules cannot be selected. Multiple H1s, an external canonical, no modification date, long prose, and no external citations are acceptable by themselves.
+
+| Exit | Meaning |
+| --- | --- |
+| 0 | Completed; no active findings meet the failure policy |
+| 1 | Completed; active errors, or warnings with `--fail-on warning` |
+| 2 | Invalid configuration/invocation, failed build/report write, resource limit, or incomplete supported-input analysis |
+| 130 | Interrupted by SIGINT |
+
+Default `fail_on: error` leaves warnings and info nonblocking. `none` disables finding-based failure; operational failures still return 2. A build with no HTML returns 2. Discovery always reports **not assessed**, owned by `jekyll-agent-discovery`.
+
+## Configuration
+
+These are the defaults, under `_config.yml`. CLI audit options override them after ordinary Jekyll config layering. Jekyll environment, drafts, future posts, URL, and baseurl retain the site's configuration.
+
+```yaml
+agent_audit:
+  fail_on: error
+  format: console
+  include: ["**/*"]
+  exclude: []
+  content:
+    selector: null
+    exclude_selectors: [nav, footer, aside, script, style, template]
+  metadata:
+    selectors:
+      author: null
+      publisher: null
+      published: null
+      modified: null
+  graph:
+    roots: ["/"]
+  routes:
+    directory_index: index.html
+    external_paths: []
+    aliases: {}
+  rules: {}
+  suppressions: []
+  limits:
+    max_html_bytes: 5242880
+    max_jsonld_bytes: 1048576
+    max_documents: 50000
+    max_edges: 1000000
+```
+
+Unknown options, rules, invalid CSS selectors, alias cycles, and malformed limits are rejected. Disable a rule with `rules: {structure.heading_jump: {enabled: false}}`. `--only` intersects enabled rules and cannot re-enable one.
+
+Include/exclude patterns match source-relative paths using Ruby `File.fnmatch?` pathname/glob semantics; exclusion wins. Excluded pages still supply links and targets to the graph. Generated HTML is included with a stable generated identity and a null source path when no source mapping is known.
+
+Graph roots are site-relative: `/` becomes `/project/` when `baseurl: /project`. Roots must exist. Route aliases and `external_paths` use full public paths, including baseurl. For example:
+
+```yaml
+agent_audit:
+  routes:
+    external_paths: ["/project/api/**"]
+    aliases:
+      /project/old-guide/: /project/guide/
+```
+
+These declarations describe hosting assumptions; they do not create or verify redirects. Assets are valid local targets. Directory-index aliases are proven by the emitted index file; `/guide` is not automatically equivalent to `/guide/`. Query strings stay in observations while target existence uses the path.
+
+Content selection uses page `agent_audit.content.selector`, site selector, unique `main`, unique main-role landmark, then unique `article`. Body fallback supports whole-document checks and skips content-sensitive headings. Ambiguous selectors produce coverage diagnostics. Metadata date selectors read machine `datetime` attributes, never free-form prose.
+
+## Suppressions
+
+Suppressions retain findings in JSON and require a reason. Site suppressions require source path scope and may specify a fingerprint. `until` is inclusive in the report's UTC reference date.
+
+```yaml
+agent_audit:
+  suppressions:
+    - rule: architecture.orphan
+      paths: ["landing/private-preview.md"]
+      reason: "Linked only from a customer email."
+      until: "2026-12-31"
+```
+
+Page front matter can use:
+
+```yaml
+agent_audit:
+  suppress:
+    - rule: structure.h1_absent
+      reason: "The layout renders the title outside main."
+```
+
+Expired suppressions do not hide findings. Unused suppressions generate notices. Collisions require a site suppression with primary-owner scope and a fingerprint. Disabling a rule appears as disabled coverage, never a clean result.
+
+## Reports and interpretation
+
+Console and JSON share one report. The [JSON schema](schema/report-1.0.json) is versioned `1.0`; consumers should tolerate additive fields and use rule IDs instead of parsing message text. Findings preserve evidence level, observation, rendered location, related locations, remediation, fingerprint, and suppression. Source lines are null unless an actual source mapping exists; rendered HTML lines are not Markdown source lines.
+
+The [example JSON report](docs/example-report.json) was generated by a fixture with a broken local link, no H1, and an explicit modification date preceding publication.
+
+Fingerprints exclude line numbers, temporary paths, message wording, and timestamps. Findings and coverage are deterministically ordered; run clocks and timings are volatile. Reports contain bounded observations, not article bodies. They can still reveal unpublished paths, so choose artifact access and retention accordingly.
+
+For every rule, `candidate = evaluated + not_applicable + skipped`. Evaluated includes clean and finding-producing applications. Suppressing a finding does not change coverage. Counts describe local observations; there is no quality percentage.
+
+## Development and release status
+
+```sh
+bundle install
+bundle exec rake test
+bundle exec rake lint
+gem build jekyll-agent-audit.gemspec
+ruby script/benchmark.rb
+```
+
+
+### Generated documentation
+
+Generate Markdown API documentation and the LLM index from the Ruby source:
+
+```sh
+bundle exec rake docs
+```
+
+This replaces `doc/` with fresh YARD Markdown, updates the documentation index in
+`doc/Jekyll/AgentAudit.md`, and writes `llms.txt` with links relative to the gem
+root. Both namespaces are indexed: the library under `Jekyll::AgentAudit` and the
+Jekyll subcommand under `Jekyll::Commands::AgentAudit`. The generated files are
+checked in and shipped with the gem; `yard` and `yard-markdown` stay development
+dependencies. Authored guides belong in `docs/`, not the generated `doc/`.
+
+For the individual steps, run `bundle exec rake yard`, then
+`ruby bin/generate_llm.rb`.
+
+To verify everything, regenerate documentation, and build the versioned gem and
+SHA-256 checksum in `pkg/`, run:
+
+```sh
+bin/prepare_release
+```
+
+It stops at the first failure and never commits, tags, pushes, or publishes.
+
+The implementation targets Jekyll 4.4.x. See [verification and compatibility](docs/verification.md) for combinations actually tested and benchmark measurements. Do not infer native GitHub Pages compatibility. The runtime HTML parser is explicitly declared as Nokogiri; no optional SEO, sitemap, or Markdown plugin is required.
+
+See [limitations and evidence](docs/limitations.md) before interpreting findings. The design specification in the parent workspace is the normative MVP catalog; deferred editorial and duplication analyses are not enabled.