docs refresh: align README/ARCHITECTURE/CONTRIBUTING/SKILLS/USAGE with current code

[Kiran01bm]

What

Cross-checked every claim in the canonical docs against the codebase
(pkg/config, pkg/types, pkg/eol/endoflife, pkg/workflow,
cmd/server/main.go), the live production dashboard
(https://blockcell.sqprod.co/sites/version-guard-dashboard/json/findings.json,
snapshot 2026-05-04T18:14:20Z), and the GitHub Actions workflows. Fixed
drift introduced by recent refactors (detector path removal, YAML-driven
EOL lifecycle, Lambda/RDS catalog additions, webhook emitter, Temporal SDK
metrics, OCI Helm release flow).

README.md

• Snapshot Schema example: replaced fictional snake-case Finding fields
  (resource_id, status, message) with the actual PascalCase shape
  (pkg/types.Finding has no JSON tags); keyed findings_by_type by the
  resource config ID (aurora-mysql) instead of the test-only
  ResourceType constant; added the scan_*_time, scan_duration_sec,
  and unknown_count fields that the writer actually emits.
• "Supported Resources" table: re-classified Aurora PostgreSQL, RDS MySQL,
  RDS PostgreSQL, and Lambda from "🔜 Config ready, needs Wiz report ID"
  to "✅ Production tested" — confirmed live by the Block dashboard
  (231 / 44 / 126 / 19,357 resources respectively). Refined Aurora MySQL
  caveat to point at the deploy/endoflife-override shim while
  endoflife-date#9534 is still open upstream.
• All three WIZ_REPORT_IDS examples now include opensearch and
  lambda (matching .env.example and the default catalog).
• Configuration env-var table: added TEMPORAL_TASK_QUEUE,
  TEMPORAL_METRICS_ENABLED, TEMPORAL_METRICS_LISTEN_ADDRESS.

ARCHITECTURE.md

• "Implementation Status": collapsed all 10 default-catalog resources
  under a single "Production-Tested" section (the previous structure
  contradicted itself by listing OpenSearch under "Planned Resources"
  with a "Production tested" description).
• Phase 1 resource line: same fix.
• Snapshot Schema: keys changed from test-only AURORA/EKS to actual
  lowercase config IDs (aurora-mysql, eks); added serialization-rules
  note; added scan_duration_sec and unknown_count.
• Python S3-trigger snippet: same key fix + finding['Status'] (PascalCase)
  • .get(..., []) for safety.
• Repository Structure: removed phantom top-level config/ and
  docs/examples/; added the actually-shipped pkg/config/transforms.go,
  pkg/config/defaults/, pkg/inventory/wiz/transforms.go,
  pkg/snapshot/memory_store.go, pkg/workflow/orchestrator/notify.go,
  pkg/schedule/, charts/, deploy/.
• EOL adapter labels: (standard, EKS) / "Why EKS needs its own adapter"
  → (standard, declarative) / "Lifecycle schema reference" — EKS no
  longer has a custom adapter; it uses schema: declarative.

CONTRIBUTING.md

• Replaced the TestDetector_Detect example (no Detector type since the
  detector path was removed in d780b93) with a TestPolicy_Classify
  example matching the real Classify(resource, lifecycle) Status
  signature.
• Integration-test build constraint: updated from legacy-only
  // +build integration to the modern //go:build integration pattern,
  with a pointer to pkg/eol/endoflife/integration_test.go and
  make test-integration.
• Project Structure: added pkg/config, pkg/registry, pkg/schedule,
  pkg/workflow/orchestrator/notify.go; clarified existing entries;
  replaced phantom top-level docs/ with charts/version-guard/ and
  deploy/.
• Release Process: replaced fictional "Update CHANGELOG.md" / "GitHub
  Actions builds artifacts" steps with the actual Docker & Helm
  workflow behavior (single vX.Y.Z tag, multi-arch image to
  ghcr.io/block/Version-Guard, OCI Helm chart to
  oci://ghcr.io/block/charts, tag-vs-Chart.yaml version guard).

SKILLS.md

• Replaced the made-up YAML examples (using fictional fields name,
  wiz_report_id, eol_product, version_field, name_field,
  schema_type — none of which exist in the real config schema) with
  concise pointers to the real example files in
  skills/add-version-guard-resource/examples/ and one paragraph
  describing the actual schema.
• Removed the false claim that Aurora PostgreSQL needs a custom Go EOL
  adapter (it uses schema: standard + a substring_lookup engine
  transform).
• SKILL.md template: fixed tool_allowlist: → allowed-tools: and added
  roles, metadata.{version,status}, user-invocable,
  disable-model-invocation to match the real frontmatter.
• Amp setup: replaced fictional amp scan skills with the real
  amp skill list / amp skill info.
• Replaced the dead https://github.com/agent-skills/specification URL
  (HTTP 404) with the live Anthropic Agent Skills engineering post.
• Troubleshooting: corrected the "Verify report ID in resources.yaml"
  guidance to point at the WIZ_REPORT_IDS env var (where the IDs
  actually live); pointed EOL product mismatch at the
  eol.schema: declarative path and pkg/eol/endoflife/ADAPTERS.md;
  pointed schema-detection issues at transforms and TRANSFORMS.md.
• Removed the dead scratch/config-driven-approach/ link
  (scratch/ is gitignored and the path doesn't exist).

USAGE.md

• Stale startup-log expectations: removed
  ✓ Total detectors initialized: 3 (the detector path was deleted in
  d780b93); replaced fixed 4 resource(s) defined with the
  parameterized N (default = 10); aligned the surviving lines with
  what cmd/server/main.go actually prints.
• "Run with Docker" section: replaced the non-existent make docker-build and version-guard:latest image with the actual
  docker build -f deploy/Dockerfile. Fixed the port mapping from
  8080:8080 to 8081:8081 + 9090:9090 (HTTP_PORT default is 8081
  and Temporal SDK metrics serve on 9090).

Files reviewed and left unchanged

• TRANSFORMS.md — DSL operations and worked examples verified against
  pkg/config/transforms.go and pkg/config/defaults/resources.yaml.
• AGENTS.md — concise and accurate.
• GOVERNANCE.md — out of scope.

Verification

• All code fences balanced (verified with awk count of triple-backticks
  per file).
• Live URLs spot-checked (Anthropic skills post returns HTTP 200; the
  removed agent-skills/specification URL was returning HTTP 404).
• Resource catalog claims cross-checked against the live production
  dashboard JSON (10/10 default-catalog resource types have findings).

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 5aec45a592

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Include every default resource in report map examples

This live-Wiz example still omits aurora-postgresql, rds-mysql, and rds-postgresql even though this same section now documents those as production-tested defaults. The server initializes all ten YAML resources into the default scan list, and GenericInventorySource.ListResources fails a resource at scan time when WIZ_REPORT_IDS[resourceID] is missing, so users copying this map will get partial scans with those default resources failing/excluded rather than the advertised full catalog.

Useful? React with 👍 / 👎.