docs: plug all documentation gaps in the v2 spec#6
Merged
Conversation
- Add description fields to all 54 schemas (top-level + all properties) - Create 41 new example files covering every schema type - Expand README with architecture diagram, layout, impl guide, validation - Rewrite schemas/README to document all 54 schemas across 9 areas - Add CONTRIBUTING.md with conventions, process, and versioning policy - Add CHANGELOG.md - Fix openapi.yaml: info.description/contact/license, GET/DELETE ops, operation summaries/descriptions, 4xx/5xx responses on all endpoints - Fix openapi.agent-plane.patch.yaml: summaries, descriptions, GET ops - Fix asyncapi.yaml: info fields, subscribe directions, 5 new channels, channel descriptions and operationIds - Fix asyncapi.agent-plane.patch.yaml: descriptions, subscribe directions - Expand semantic/context.jsonld from 7 to 54 type mappings - Expand semantic/hydra.jsonld from 2 to 21 hydra:supportedClass entries - Add docs/adr/ with 5 Architecture Decision Records (ADR-0001 to 0005) - Add .github/workflows/validate.yml CI for schema + example validation - Fix .github/PULL_REQUEST_TEMPLATE.md with a real PR checklist - Remove .IMPORT_SOURCE.txt and pulls/ import artifacts Agent-Logs-Url: https://github.com/SourceOS-Linux/sourceos-spec/sessions/cb979b64-c02a-47d0-a09f-7d1bfedeeb7c Co-authored-by: mdheller <21163552+mdheller@users.noreply.github.com>
Agent-Logs-Url: https://github.com/SourceOS-Linux/sourceos-spec/sessions/cb979b64-c02a-47d0-a09f-7d1bfedeeb7c Co-authored-by: mdheller <21163552+mdheller@users.noreply.github.com>
Copilot created this pull request from a session on behalf of
mdheller
April 8, 2026 18:44
View session
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 0a4318fc13
ℹ️ 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".
…cts-for-main chore: document merge-to-main conflict reconciliation in CHANGELOG
…tation-coverage # Conflicts: # .github/PULL_REQUEST_TEMPLATE.md # CHANGELOG.md # CONTRIBUTING.md # README.md # asyncapi.agent-plane.patch.yaml # asyncapi.yaml # examples/community.json # examples/rating.json # openapi.agent-plane.patch.yaml # openapi.yaml # schemas/AgentSession.json # schemas/Agreement.json # schemas/AuthorityLink.json # schemas/CapabilityToken.json # schemas/Comment.json # schemas/Community.json # schemas/Connector.json # schemas/DataRef.json # schemas/DataSphere.json # schemas/Dataset.json # schemas/EntityField.json # schemas/EventEnvelope.json # schemas/Exception.json # schemas/ExecutionDecision.json # schemas/ExecutionSurface.json # schemas/ExperimentFlag.json # schemas/Field.json # schemas/FrustrationSignal.json # schemas/GlossaryTerm.json # schemas/Link.json # schemas/MappingEvidence.json # schemas/MappingSpec.json # schemas/MemoryEntry.json # schemas/ObjectContext.json # schemas/ObjectSelector.json # schemas/Obligation.json # schemas/Party.json # schemas/PhysicalAsset.json # schemas/Policy.json # schemas/PolicyBinding.json # schemas/PolicyCondition.json # schemas/PolicyDecision.json # schemas/ProfileStats.json # schemas/ProvenanceRecord.json # schemas/QualityMetric.json # schemas/README.md # schemas/Rating.json # schemas/ReleaseReceipt.json # schemas/RolloutPolicy.json # schemas/Rule.json # schemas/RunRecord.json # schemas/SchemaDefinition.json # schemas/SessionReceipt.json # schemas/SessionReview.json # schemas/SkillManifest.json # schemas/SubjectContext.json # schemas/SubjectSelector.json # schemas/TagAssignment.json # schemas/TelemetryEvent.json # schemas/Trigger.json # schemas/ValidValues.json # schemas/WorkflowEdge.json # schemas/WorkflowNode.json # schemas/WorkflowSpec.json # schemas/WorkloadSpec.json # semantic/context.jsonld # semantic/hydra.jsonld Co-authored-by: mdheller <21163552+mdheller@users.noreply.github.com>
- README.md: remove stale "Starter Kit (v2)" preamble prepended by merge - Delete PHASE_2_SCHEMA_DOCUMENTATION.md (stale development artifact) - ADRs: consolidate 10 files (5 duplicate topics, conflicting numbers) into 6 clean files (0000-template + 0001-0005); each ADR number now unique and matches its title; best content from both branches preserved - Examples: remove 15 camelCase duplicates (agentsession.json, etc.), keeping canonical snake_case versions which are more complete - Examples: remove event.json (superseded by event_envelope.json) and token.json (superseded by capability_token.json) - Examples: rename decision.json → policy_decision.json (aligns with schema naming convention) - examples/README.md: update all filename references to snake_case canonical names (17 occurrences across the narrative table and flow diagrams) - Validation: 27/27 type-bearing examples pass schema validation, 0 failures Agent-Logs-Url: https://github.com/SourceOS-Linux/sourceos-spec/sessions/1321d20d-8635-4cb5-b07e-8bc691db60fe Co-authored-by: mdheller <21163552+mdheller@users.noreply.github.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.