docs: comprehensive documentation gap remediation — world-class spec

[Copilot]

Summary

Closes every documentation gap identified in the prior audit. The repository now meets the bar expected of a production-quality, multi-language specification project.

---

Changes

Phase 1 – Prose documentation

• README.md — Complete rewrite: project introduction, schema-family table, repo layout map, quick-start code blocks (AJV, Python, quicktype, FastAPI codegen), compatibility discipline section, and links to all new docs.
• ARCHITECTURE.md(new) — Two-plane architecture diagram, schema family tables (all 54 schemas catalogued), governance lifecycle sequence, complete URN identity table, patch-file composition model, and semantic overlay guide.
• CONTRIBUTING.md(new) — Schema authoring rules (description required, additionalProperties: false required, URN patterns), URN naming guide, step-by-step guide for adding a new schema, breaking-vs-additive version policy, and full PR checklist.
• CHANGELOG.md(new) — Keep-a-Changelog format; v2.0.0 history and an [Unreleased] section covering this PR.
• docs/adr/(new) — Four Architecture Decision Records: URN identity scheme, typed PolicyCondition expression languages, agent-plane patch-file model, JSON Schema 2020-12 choice.
• schemas/README.md — Rewritten from scratch: corrected URN prefixes (urn:sourceos: → urn:srcos:), all 54 schemas catalogued in family tables, accurate AJV validation examples.
• examples/README.md(new) — Full file index with cross-reference URN story, validation instructions, and link to CONTRIBUTING.
• semantic/README.md(new) — JSON-LD framing guide, Hydra /.well-known/hydra usage, extension instructions.
• .github/PULL_REQUEST_TEMPLATE.md — Expanded from a single line (ready_for_review: true) to a structured PR template with change-type checklist, full contribution checklist, and validation commands.
• .gitignore — Added pulls/ to prevent stray GitHub API artifacts from being committed.

Phase 2 – Schema annotations

• Added top-level description to all 54 schemas (0 → 54).
• Added description to every property across all schemas (~600 annotations).

Phase 3 – API spec improvements

• openapi.yaml — Added info.description, securitySchemes (Bearer JWT), 5 tag definitions, summary + description on all 16 operations, and 400 / 401 / 403 / 422 error responses everywhere.
• openapi.agent-plane.patch.yaml — Same treatment on all 5 operations.
• asyncapi.yaml — Added info.description, servers block (dev + prod Kafka), channel and message description / title / summary, and Kafka bindings with topic config (partitions, replicas, retention) on all 5 channels.
• asyncapi.agent-plane.patch.yaml — Same on all 5 channels.

Phase 4 – Missing examples

Added 16 example files to cover all 27 top-level schema types (was 13). New files: agentsession.json, executiondecision.json, sessionreceipt.json, sessionreview.json, skillmanifest.json, memory.json, telemetry.json, frustration.json, capabilitytoken.json, workflow.json, datasphere.json, experimentflag.json, rolloutpolicy.json, releasereceipt.json, rating.json, community.json.

Phase 5 – Semantic layer

• context.jsonld — Expanded from 7 to 54 type mappings; added prov: and schema: prefixes.
• hydra.jsonld — Expanded from 2 to 21 hydra:supportedClass entries (all with hydra:title, hydra:description, and operations); deduplicated the @context block; added hydra:description to the API documentation root.

Checklist

• No breaking changes to any existing schema
• All 54 schemas pass the annotation completeness check
• All 27 top-level schema types have conforming example files
• All 16 OpenAPI operations have summary + description + error responses
• All 10 AsyncAPI channels have descriptions and Kafka bindings
• Code review passed with no comments
• CodeQL scan passed (no analysable code changes)