@bluefly/openstandardagents 0.2.4 → 0.2.7

package/website/content/docs/migration-guides/drupal-eca-to-ossa.md

@@ -152,7 +152,7 @@ events:
 
 **OSSA Agent (Webhook Integration):**
 ```yaml
-ossaVersion: '1.0'
+ossaVersion: "0.2.6"
 agent:
   id: drupal-content-handler
   name: Drupal Content Handler Agent
@@ -225,7 +225,7 @@ conditions:
 
 **OSSA Agent (Schema + Policy Enforcement):**
 ```yaml
-ossaVersion: '1.0'
+ossaVersion: "0.2.6"
 agent:
   id: content-moderator
   name: Content Moderation Agent
@@ -283,7 +283,7 @@ actions:
 
 **OSSA Agent (Multi-Capability):**
 ```yaml
-ossaVersion: '1.0'
+ossaVersion: "0.2.6"
 agent:
   id: content-processor
   name: Content Processing Agent
@@ -475,7 +475,7 @@ workflow:
 
 **OSSA Orchestrator Agent:**
 ```yaml
-ossaVersion: '1.0'
+ossaVersion: "0.2.6"
 agent:
   id: content-workflow-orchestrator
   name: Content Workflow Orchestrator
@@ -673,7 +673,7 @@ actions:
 
 ```yaml
 # drupal-content-moderator.ossa.yaml
-ossaVersion: '1.0'
+ossaVersion: "0.2.6"
 
 agent:
   id: drupal-content-moderator
@@ -962,7 +962,7 @@ actions:
 
 ```yaml
 # user-onboarding-agent.ossa.yaml
-ossaVersion: '1.0'
+ossaVersion: "0.2.6"
 
 agent:
   id: user-onboarding-orchestrator
@@ -1272,7 +1272,7 @@ actions:
 
 ```yaml
 # commerce-order-processor.ossa.yaml
-ossaVersion: '1.0'
+ossaVersion: "0.2.6"
 
 agent:
   id: commerce-order-processor
@@ -1943,19 +1943,19 @@ if ($features->isEnabled('ossa_moderation')) {
 ### Documentation
 - [OSSA Specification](https://github.com/blueflyio/openstandardagents/wiki/home)
 - [Drupal ECA Guide](https://ecaguide.org/)
-- [BuildKit CLI Reference](https://github.com/blueflyio/openstandardagents/wiki/BuildKit-CLI-Reference)
+- [BuildKit CLI Reference](https://github.com/blueflyio/documentation/-/wikis/BuildKit-CLI-Reference)
 
 ### Tools
-- OSSA CLI: `npm install -g @bluefly/openstandardagents`
+- OSSA CLI: `npm install -g @ossa/cli`
 - BuildKit: `npm install -g @llm/agent-buildkit`
 - OSSA Validator: `ossa validate <file>`
 
 ### Examples
 - [OSSA Example Agents](https://github.com/blueflyio/openstandardagents/tree/main/examples)
-- [Drupal Integration Module](https://github.com/blueflyio/openstandardagents)
+- [Drupal Integration Module](https://github.com/blueflyio/drupal/ossa_integration)
 
 ### Support
-- [GitHub Issues](https://github.com/blueflyio/openstandardagents/issues)
+- [GitLab Issues](https://github.com/blueflyio/documentation/-/issues)
 - [OSSA Discussions](https://github.com/blueflyio/openstandardagents/issues)
 
 ---

package/{docs/migration → website/content/docs/migration-guides}/general-agent-schema.yml

@@ -26,15 +26,7 @@ components:
           type: array
           items:
             type: string
-            enum:
-              [
-                code_generation,
-                code_review,
-                issue_analysis,
-                documentation,
-                testing,
-                deployment,
-              ]
+            enum: [code_generation, code_review, issue_analysis, documentation, testing, deployment]
         configuration:
           type: object
           properties:

package/website/content/docs/migration-guides/index.md

@@ -116,7 +116,7 @@ Starting fresh? → Check Getting Started guide
 
 - **Documentation:** `/Users/flux423/Sites/LLM/agent-buildkit/docs/`
 - **Examples:** `/Users/flux423/Sites/LLM/agent-buildkit/.agents/`
-- **OSSA Spec:** [OSSA Complete Reference](../OSSA-COMPLETE-AGENT-REFERENCE.md)
+- **OSSA Spec:** [Schema Reference](/docs/schema-reference)
 - **BuildKit CLI:** `buildkit agents --help`
 
 ## Contributing

package/website/content/docs/migration-guides/langchain-to-ossa.md

@@ -173,7 +173,7 @@ print(result)
 **Step 1: Create agent manifest** - `.agents/assistant-agent/agent.yml`
 
 ```yaml
-ossaVersion: "1.0"
+ossaVersion: "0.2.6"
 metadata:
   name: assistant-agent
   version: "1.0.0"
@@ -471,7 +471,7 @@ agent.run("What's my name?")  # Should remember "Alice"
 **Agent manifest** - `.agents/conversational-agent/agent.yml`
 
 ```yaml
-ossaVersion: "1.0"
+ossaVersion: "0.2.6"
 metadata:
   name: conversational-agent
   version: "1.0.0"
@@ -799,7 +799,7 @@ print(f"Story: {result['story']}")
 **Agent manifest** - `.agents/story-writer-agent/agent.yml`
 
 ```yaml
-ossaVersion: "1.0"
+ossaVersion: "0.2.6"
 metadata:
   name: story-writer-agent
   version: "1.0.0"
@@ -1257,7 +1257,7 @@ final = editor.run(f"Edit this draft: {draft}")
 Use orchestrator agent with A2A (Agent-to-Agent) communication:
 
 ```yaml
-ossaVersion: "1.0"
+ossaVersion: "0.2.6"
 agent:
   id: article-orchestrator
   name: Article Orchestrator
@@ -1617,9 +1617,9 @@ Use feature flags or load balancer to control traffic split.
 
 5. **Join the community**
    - [OSSA Specification](https://github.com/blueflyio/openstandardagents/wiki/home)
-   - [Agent BuildKit](https://github.com/blueflyio/openstandardagents)
-   - [Examples Repository](https://github.com/blueflyio/openstandardagents/tree/main/examples)
-   - [Issue Tracker](https://github.com/blueflyio/openstandardagents/issues)
+   - [Agent BuildKit](https://github.com/blueflyio/agent-buildkit)
+   - [Examples Repository](https://github.com/blueflyio/agent-buildkit/-/tree/main/examples)
+   - [Issue Tracker](https://github.com/blueflyio/agent-buildkit/-/issues)
 
 ---
 
@@ -1633,19 +1633,19 @@ Use feature flags or load balancer to control traffic split.
 - [Getting Started Guide](/Getting-Started)
 
 ### Examples
-- [Simple Worker Agent](https://github.com/blueflyio/openstandardagents/tree/main/agents/review-agents)
-- [Orchestrator Agent](https://github.com/blueflyio/openstandardagents/tree/main/agents/executive-agents)
-- [Multi-Agent System](https://github.com/blueflyio/openstandardagents/tree/main/examples)
+- [Simple Worker Agent](https://github.com/blueflyio/agent-buildkit/-/tree/main/agents/review-agents)
+- [Orchestrator Agent](https://github.com/blueflyio/agent-buildkit/-/tree/main/agents/executive-agents)
+- [Multi-Agent System](https://github.com/blueflyio/agent-buildkit/-/tree/main/examples)
 
 ### Tools
-- [Agent Validator](https://github.com/blueflyio/openstandardagents/blob/main/src/cli/agents/validate.ts)
-- [Migration Script](https://github.com/blueflyio/openstandardagents/blob/main/scripts/migrate-agents-to-ossa.ts)
-- [Agent Templates](https://github.com/blueflyio/openstandardagents/tree/main/templates/agents)
+- [Agent Validator](https://github.com/blueflyio/agent-buildkit/-/blob/main/src/cli/agents/validate.ts)
+- [Migration Script](https://github.com/blueflyio/agent-buildkit/-/blob/main/scripts/migrate-agents-to-ossa.ts)
+- [Agent Templates](https://github.com/blueflyio/agent-buildkit/-/tree/main/templates/agents)
 
 ### Support
-- **Issues**: https://github.com/blueflyio/openstandardagents/issues
-- **Discussions**: https://github.com/blueflyio/openstandardagents/pulls
-- **Wiki**: https://github.com/blueflyio/openstandardagents/wiki/home
+- **Issues**: https://github.com/blueflyio/agent-buildkit/-/issues
+- **Discussions**: https://github.com/blueflyio/agent-buildkit/-/merge_requests
+- **Wiki**: https://github.com/blueflyio/agent-buildkit/-/wikis/home
 
 ---
 
@@ -1711,4 +1711,4 @@ runtime:
 
 ---
 
-*For questions or issues with this migration guide, please create an issue at: https://github.com/blueflyio/openstandardagents/issues*
+*For questions or issues with this migration guide, please create an issue at: https://github.com/blueflyio/agent-buildkit/-/issues*

package/website/content/docs/migration-guides/langflow-to-ossa.md

@@ -2052,7 +2052,7 @@ ossa-migrate validate \
 
 - **OSSA Specification**: https://github.com/blueflyio/openstandardagents/wiki/home
 - **OSSA Quick Reference**: [OSSA-QUICK-REFERENCE.md](../OSSA-QUICK-REFERENCE.md)
-- **BuildKit CLI**: https://github.com/blueflyio/openstandardagents/wiki/BuildKit-CLI-Reference
+- **BuildKit CLI**: https://github.com/blueflyio/documentation/-/wikis/BuildKit-CLI-Reference
 - **Langflow Documentation**: https://docs.langflow.org/
 
 ### Example Repositories
@@ -2062,7 +2062,7 @@ ossa-migrate validate \
 
 ### Community & Support
 
-- **GitHub Issues**: https://github.com/blueflyio/openstandardagents/issues
+- **GitLab Issues**: https://github.com/blueflyio/documentation/-/issues
 - **Migration Support**: Tag issues with `migration::langflow`
 
 ---
@@ -2072,4 +2072,4 @@ ossa-migrate validate \
 **Maintained By:** OSSA Team
 **License:** MIT
 
-**Feedback**: Please report issues or suggestions at https://github.com/blueflyio/openstandardagents/issues/new?issue[title]=Langflow%20Migration%20Guide%20Feedback
+**Feedback**: Please report issues or suggestions at https://github.com/blueflyio/documentation/-/issues/new?issue[title]=Langflow%20Migration%20Guide%20Feedback

package/website/content/docs/migration-guides/openai-to-ossa.md

@@ -83,7 +83,7 @@ assistant = client.beta.assistants.create(
 
 **OSSA Equivalent:**
 ```yaml
-apiVersion: ossa/v0.2.3
+apiVersion: ossa/v0.2.2
 kind: Agent
 metadata:
   name: data-analyst
@@ -203,7 +203,7 @@ assistant = client.beta.assistants.create(
 
 **OSSA Data Capabilities:**
 ```yaml
-apiVersion: ossa/v0.2.3
+apiVersion: ossa/v0.2.2
 kind: Agent
 metadata:
   name: research-assistant
@@ -397,7 +397,7 @@ print(messages.data[0].content[0].text.value)
 
 **1. Create Agent Manifest (`math-tutor.ossa.yaml`):**
 ```yaml
-apiVersion: ossa/v0.2.3
+apiVersion: ossa/v0.2.2
 kind: Agent
 metadata:
   name: math-tutor
@@ -528,7 +528,7 @@ if run.status == 'requires_action':
 
 **1. Create Agent Manifest (`stock-assistant.ossa.yaml`):**
 ```yaml
-apiVersion: ossa/v0.2.3
+apiVersion: ossa/v0.2.2
 kind: Agent
 metadata:
   name: stock-assistant
@@ -696,7 +696,7 @@ buildkit ecosystem services start qdrant
 
 **2. Create Agent Manifest (`support-assistant.ossa.yaml`):**
 ```yaml
-apiVersion: ossa/v0.2.3
+apiVersion: ossa/v0.2.2
 kind: Agent
 metadata:
   name: support-assistant
@@ -905,7 +905,7 @@ OSSA provides native support for multi-agent orchestration, which OpenAI Assista
 
 **OSSA Orchestrator Example:**
 ```yaml
-apiVersion: ossa/v0.2.3
+apiVersion: ossa/v0.2.2
 kind: Agent
 metadata:
   name: research-orchestrator
@@ -1181,7 +1181,7 @@ curl http://localhost:3000/metrics
 ## Additional Resources
 
 - **OSSA Specification**: [https://github.com/blueflyio/openstandardagents/wiki/home](https://github.com/blueflyio/openstandardagents/wiki/home)
-- **BuildKit Documentation**: [https://github.com/blueflyio/openstandardagents/wiki/BuildKit-CLI-Reference](https://github.com/blueflyio/openstandardagents/wiki/BuildKit-CLI-Reference)
+- **BuildKit Documentation**: [https://github.com/blueflyio/documentation/-/wikis/BuildKit-CLI-Reference](https://github.com/blueflyio/documentation/-/wikis/BuildKit-CLI-Reference)
 - **Agent Examples**: `/Users/flux423/Sites/LLM/agent-buildkit/templates/agents/`
 - **OSSA Types**: `/Users/flux423/Sites/LLM/agent-buildkit/src/types/ossa.ts`
 - **OpenAPI Spec**: `/Users/flux423/Sites/LLM/agent-buildkit/openapi/ossa-complete-v0.1.2.yaml`
@@ -1190,9 +1190,9 @@ curl http://localhost:3000/metrics
 
 ## Support
 
-- **Issues**: [https://github.com/blueflyio/openstandardagents/issues](https://github.com/blueflyio/openstandardagents/issues)
-- **BuildKit Repo**: [https://github.com/blueflyio/openstandardagents](https://github.com/blueflyio/openstandardagents)
-- **Wiki**: [https://github.com/blueflyio/openstandardagents/wiki/home](https://github.com/blueflyio/openstandardagents/wiki/home)
+- **Issues**: [https://github.com/blueflyio/documentation/-/issues](https://github.com/blueflyio/documentation/-/issues)
+- **BuildKit Repo**: [https://github.com/blueflyio/agent-buildkit](https://github.com/blueflyio/agent-buildkit)
+- **Wiki**: [https://github.com/blueflyio/documentation/-/wikis/home](https://github.com/blueflyio/documentation/-/wikis/home)
 
 ---
 

package/website/content/docs/openapi-extensions/examples.md

@@ -16,13 +16,13 @@ info:
   description: Minimal OSSA-compliant agent API
 
 x-ossa-metadata:
-  version: 0.2.2
+  version: 0.2.x
   compliance:
     level: basic
     frameworks: [OSSA, OpenAPI 3.1]
 
 x-ossa:
-  version: 0.2.2
+  version: 0.2.x
   agent:
     id: hello-world-agent
     type: worker
@@ -89,7 +89,7 @@ info:
     Supports pod inspection, log analysis, and event correlation.
 
 x-ossa-metadata:
-  version: 0.2.2
+  version: 0.2.x
   compliance:
     level: enterprise
     frameworks:
@@ -110,7 +110,7 @@ x-ossa-metadata:
     logging: true
 
 x-ossa:
-  version: 0.2.2
+  version: 0.2.x
   agent:
     id: k8s-troubleshooter
     type: worker
@@ -268,13 +268,13 @@ info:
   version: 1.0.0
 
 x-ossa-metadata:
-  version: 0.2.2
+  version: 0.2.x
   compliance:
     level: standard
     frameworks: [OSSA, OpenAPI 3.1]
 
 x-ossa:
-  version: 0.2.2
+  version: 0.2.x
   agent:
     id: data-processor
     type: worker
@@ -392,7 +392,7 @@ The OpenAPI spec should reference capabilities and tools defined in the manifest
 
 **agent.ossa.yaml**:
 ```yaml
-apiVersion: ossa/v0.2.3
+apiVersion: ossa/v0.2.x
 kind: Agent
 metadata:
   name: k8s-troubleshooter
@@ -461,7 +461,7 @@ info:
   version: 1.0.0
 
 x-ossa:
-  version: 0.2.2
+  version: 0.2.x
   agent:
     id: devops-assistant
     type: worker
@@ -546,5 +546,5 @@ paths:
 
 - [Root-Level Extensions](root-extensions)
 - [Operation-Level Extensions](operation-extensions)
-- [OSSA Specification v0.2.2](../Technical/Specification-Deep-Dive)
+- [OSSA Specification](/docs/specification)
 - [OpenAPI 3.1 Specification](https://spec.openapis.org/oas/v3.1.0)

package/website/content/docs/openapi-extensions/index.md

@@ -45,7 +45,7 @@ info:
   version: 1.0.0
 
 x-ossa-metadata:
-  version: 0.2.2
+  version: 0.2.x
   compliance:
     level: enterprise
     frameworks:
@@ -78,7 +78,7 @@ Core OSSA compliance information with agent identification and validation metada
 
 ```yaml
 x-ossa:
-  version: 0.2.2
+  version: 0.2.x
   agent:
     id: k8s-troubleshooter
     type: worker
@@ -395,7 +395,7 @@ See [Full Documentation](https://github.com/blueflyio/openstandardagents/blob/ma
 - **Full Documentation**: [docs/openapi-extensions.md](https://github.com/blueflyio/openstandardagents/blob/main/docs/openapi-extensions.md)
 - **JSON Schema**: [docs/schemas/openapi-extensions.schema.json](https://github.com/blueflyio/openstandardagents/blob/main/docs/schemas/openapi-extensions.schema.json)
 - **Examples**: [examples/openapi-extensions/](https://github.com/blueflyio/openstandardagents/tree/main/examples/openapi-extensions)
-- **OSSA Specification**: [spec/v0.2.2/OSSA-SPECIFICATION-v0.2.2.md](https://github.com/blueflyio/openstandardagents/blob/main/spec/v0.2.2/OSSA-SPECIFICATION-v0.2.2.md)
+- **OSSA Specification**: [spec/v0.2.6/OSSA-SPECIFICATION-v0.2.x.md](https://github.com/blueflyio/openstandardagents/blob/main/spec/v0.2.6/OSSA-SPECIFICATION-v0.2.2.md)
 - **npm Package**: [@bluefly/openstandardagents](https://www.npmjs.com/package/@bluefly/openstandardagents)
 
 ---
@@ -403,6 +403,62 @@ See [Full Documentation](https://github.com/blueflyio/openstandardagents/blob/ma
 *For complete documentation with all examples and details, see the [main documentation file](https://github.com/blueflyio/openstandardagents/blob/main/docs/openapi-extensions.md).*
 
 
+---
+
+## Integration with OSSA Manifests
+
+OSSA OpenAPI extensions complement OSSA agent manifests (`.ossa.yaml` files). They serve different but related purposes:
+
+- **OSSA Agent Manifest** (`.ossa.yaml`) - Declarative agent definition with full configuration, capabilities, tools, LLM settings, and runtime configuration
+- **OpenAPI Specification with OSSA Extensions** - API interface definition with agent metadata, operation-level autonomy, constraints, and tool requirements
+
+### When to Use Each
+
+**Use OSSA Manifest (`.ossa.yaml`)** when:
+- Defining the complete agent configuration
+- Specifying runtime environment (k8s, docker, serverless)
+- Declaring all agent capabilities in one place
+- Configuring default LLM settings
+- Defining agent-to-agent communication protocols
+
+**Use OpenAPI with OSSA Extensions** when:
+- Documenting REST API endpoints
+- Linking API operations to agent capabilities
+- Defining operation-specific autonomy levels
+- Setting per-operation cost and performance constraints
+- Specifying which tools are needed for each API call
+
+### Combining Both
+
+You can use both together:
+
+1. **OSSA Manifest** defines the agent's overall configuration
+2. **OpenAPI Spec** defines the API interface with OSSA extensions
+3. The `x-ossa-capability` extension links API operations to capabilities defined in the manifest
+
+Example workflow:
+```yaml
+# agent.ossa.yaml
+apiVersion: ossa/v0.2.x
+kind: Agent
+metadata:
+  name: data-processor
+spec:
+  capabilities:
+    - name: data-transformation
+      description: Transform CSV to JSON
+      # ... capability config ...
+
+# agent.openapi.yml
+openapi: 3.1.0
+paths:
+  /api/v1/transform:
+    post:
+      x-ossa-capability:
+        name: data-transformation  # Links to capability in manifest
+      # ... operation config ...
+```
+
 ---
 
 ## Governance & Autonomy Guidance

package/website/content/docs/openapi-extensions/operation-extensions.md

@@ -20,11 +20,24 @@ x-ossa-capability: "capability-name"
 ```
 
 **Detailed object**:
+```yaml
+x-ossa-capability:
+  name: string                 # Capability name
+  description: string          # Capability description (optional)
+  input: boolean              # Whether this is an input capability (optional)
+  output: boolean             # Whether this is an output capability (optional)
+  inputSchema: object         # JSON Schema for capability input (optional)
+  outputSchema: object         # JSON Schema for capability output (optional)
+```
+
+**Schema Reference Table:**
 
 | Field | Type | Description |
 |-------|------|-------------|
 | `name` | string | Capability name |
 | `description` | string | Capability description (optional) |
+| `input` | boolean | Whether this is an input capability (optional) |
+| `output` | boolean | Whether this is an output capability (optional) |
 | `inputSchema` | object | JSON Schema for capability input (optional) |
 | `outputSchema` | object | JSON Schema for capability output (optional) |
 
@@ -80,6 +93,16 @@ Operation object within path item
 
 ### Schema
 
+```yaml
+x-ossa-autonomy:
+  level: string                # "supervised" | "semi-autonomous" | "autonomous"
+  approval_required: boolean   # Whether human approval is required
+  allowed_actions: string[]   # List of allowed actions (optional)
+  blocked_actions: string[]   # List of blocked actions (optional)
+```
+
+**Schema Reference Table:**
+
 | Field | Type | Description |
 |-------|------|-------------|
 | `level` | string | Autonomy level: "supervised" \| "autonomous" \| "semi-autonomous" |
@@ -137,6 +160,22 @@ Operation object within path item
 
 ### Schema
 
+```yaml
+x-ossa-constraints:
+  cost:
+    maxTokensPerDay: integer   # Maximum tokens allowed per day
+    maxTokensPerRequest: integer # Maximum tokens allowed per request
+    maxCostPerDay: number      # Maximum cost in USD per day
+    currency: string           # Currency code (default: "USD")
+  performance:
+    maxLatencySeconds: number  # Maximum acceptable latency in seconds
+    maxConcurrentRequests: integer # Maximum concurrent requests
+  time:
+    maxExecutionTime: integer  # Maximum execution time in seconds
+```
+
+**Schema Reference Table:**
+
 | Field | Type | Description |
 |-------|------|-------------|
 | `cost.maxTokensPerDay` | integer | Maximum tokens allowed per day |
@@ -191,7 +230,17 @@ Operation object within path item
 
 ### Schema
 
-Each tool is an object with:
+Each tool is an object in an array:
+
+```yaml
+x-ossa-tools:
+  - type: string               # "mcp" | "http" | "custom"
+    server: string             # Tool server identifier or URL
+    namespace: string          # Namespace for the tool (optional, for MCP servers)
+    capabilities: string[]     # List of tool capabilities (optional)
+```
+
+**Schema Reference Table:**
 
 | Field | Type | Description |
 |-------|------|-------------|
@@ -248,6 +297,16 @@ Operation object within path item
 
 ### Schema
 
+```yaml
+x-ossa-llm:
+  provider: string             # "openai" | "anthropic" | "google" | "azure" | "custom"
+  model: string                # Model identifier (e.g., "gpt-4", "claude-3-opus")
+  temperature: number          # Sampling temperature (0-2, optional)
+  maxTokens: integer           # Maximum tokens in response (optional)
+```
+
+**Schema Reference Table:**
+
 | Field | Type | Description |
 |-------|------|-------------|
 | `provider` | string | Provider: "openai" \| "anthropic" \| "google" \| "azure" \| "custom" |
@@ -394,5 +453,5 @@ paths:
 
 - [Root-Level Extensions](root-extensions)
 - [Examples & Patterns](examples)
-- [OSSA Specification v0.2.2](../Technical/Specification-Deep-Dive)
+- [OSSA Specification](/docs/specification)
 - [OpenAPI 3.1 Specification](https://spec.openapis.org/oas/v3.1.0)

package/website/content/docs/openapi-extensions/root-extensions.md

@@ -14,6 +14,28 @@ Root level of OpenAPI spec
 
 ### Schema
 
+```yaml
+x-ossa-metadata:
+  version: string              # OSSA specification version (e.g., "0.2.2", "1.0.0")
+  compliance:
+    level: string              # "basic" | "standard" | "advanced" | "enterprise"
+    frameworks: string[]       # List of compliance frameworks
+  governance:
+    approved: boolean          # Whether specification has been approved
+    approvedBy: string         # Entity that approved (optional)
+    approvalDate: string       # Date of approval in YYYY-MM-DD format (optional)
+  security:
+    classification: string     # "public" | "internal" | "confidential" | "restricted"
+    authentication: string     # "required" | "optional" | "none"
+    encryption: string         # Encryption requirements (e.g., "tls1.3")
+  observability:
+    tracing: boolean           # Enable distributed tracing
+    metrics: boolean           # Enable metrics collection
+    logging: boolean           # Enable structured logging
+```
+
+**Schema Reference Table:**
+
 | Field | Type | Description |
 |-------|------|-------------|
 | `version` | string | OSSA specification version (e.g., "0.2.2", "1.0.0") |
@@ -38,7 +60,7 @@ info:
   version: 1.0.0
 
 x-ossa-metadata:
-  version: 0.2.2
+  version: 0.2.x
   compliance:
     level: enterprise
     frameworks:
@@ -115,6 +137,20 @@ Root level or `info` section of OpenAPI spec
 
 ### Schema
 
+```yaml
+x-ossa:
+  version: string              # OSSA specification version (e.g., "0.2.2")
+  agent:
+    id: string                 # Unique agent identifier (DNS subdomain format)
+    type: string               # Agent type (see table below)
+    compliance:
+      standards: string[]      # Architectural standards (e.g., ["openapi-first", "dry", "solid"])
+      validated: boolean       # Whether agent has been validated
+      validatedAt: string      # ISO 8601 timestamp of validation
+```
+
+**Schema Reference Table:**
+
 | Field | Type | Description |
 |-------|------|-------------|
 | `version` | string | OSSA specification version (e.g., "0.2.2") |
@@ -148,7 +184,7 @@ info:
   version: 1.0.0
 
 x-ossa:
-  version: 0.2.2
+  version: 0.2.x
   agent:
     id: k8s-troubleshooter
     type: worker
@@ -185,6 +221,16 @@ Root level or `info` section of OpenAPI spec
 
 ### Schema
 
+```yaml
+x-agent:
+  capabilities: string[]       # List of agent capability names
+  tools: string[]             # List of tools/MCP servers available
+  environment: object         # Environment-specific configuration (key-value pairs)
+  rules: string[]             # List of rules or policies the agent follows
+```
+
+**Schema Reference Table:**
+
 | Field | Type | Description |
 |-------|------|-------------|
 | `capabilities` | string[] | List of agent capability names |
@@ -360,5 +406,5 @@ components:
 
 - [Operation-Level Extensions](operation-extensions)
 - [Examples & Patterns](examples)
-- [OSSA Specification v0.2.2](../Technical/Specification-Deep-Dive)
+- [OSSA Specification](/docs/specification)
 - [OpenAPI 3.1 Specification](https://spec.openapis.org/oas/v3.1.0)