docs: extend language and skill format for CognitiveState v1 namespaces

Author: gfernandf

docs/LANGUAGE.md

@@ -116,17 +116,35 @@ Each step defines:
 
 The registry language supports references between values.
 
-Supported reference types:
+Supported reference types (legacy):
 
     inputs.<field>
     vars.<field>
     outputs.<field>
 
+CognitiveState v1 reference types (runtime extension):
+
+    frame.<path>
+    working.<path>
+    output.<path>
+    extensions.<path>
+
+CognitiveState v1 namespaces are supported by the `agent-skills` runtime.
+They provide structured cognitive processing for multi-step reasoning skills.
+Legacy references remain the default and work in all runtimes.
+
+Path traversal supports nested access (dict keys, list indices):
+
+    frame.constraints.budget
+    working.entities.0.name
+
 Examples:
 
     inputs.url
     vars.text
     outputs.summary
+    frame.goal
+    working.artifacts.draft
 
 ------------------------------------------------------------------------
 
@@ -142,6 +160,13 @@ Data may flow through:
 -   `vars`
 -   `outputs`
 
+CognitiveState v1 adds four additional namespaces (runtime extension):
+
+-   `frame` (read-only reasoning context)
+-   `working` (mutable cognitive working memory)
+-   `output` (structured result metadata)
+-   `extensions` (open namespace for plugins)
+
 ### Inputs
 
 Provided by the caller.
@@ -213,6 +238,11 @@ Simplified reference grammar:
 
     reference := inputs.field | vars.field | outputs.field
 
+CognitiveState v1 extended grammar (runtime extension):
+
+    reference := inputs.field | vars.field | outputs.field
+               | frame.path | working.path | output.path | extensions.path
+
 Capability identifier grammar:
 
     domain.noun.verb

docs/SKILL_FORMAT.md

@@ -530,31 +530,70 @@ vars.*
 outputs.*
 ```
 
+CognitiveState v1 also supports (agent-skills runtime extension):
+
+```
+working.*
+output.*
+extensions.*
+```
+
 Example:
 
 ```yaml
 output:
   summary: outputs.summary
 ```
 
+CognitiveState v1 example:
+
+```yaml
+output:
+  entities: working.entities
+  draft: working.artifacts.first_draft
+  quality: output.result_type
+```
+
 ---
 
 # Valid References
 
-Skills support only the following reference forms:
+Skills support the following reference forms:
+
+Legacy (all runtimes):
 
 ```
 inputs.*
 vars.*
 outputs.*
 ```
 
+CognitiveState v1 (agent-skills runtime extension):
+
+```
+frame.*
+working.*
+output.*
+extensions.*
+```
+
+CognitiveState v1 references support nested path traversal (dict keys, list indices):
+
+```
+frame.constraints.budget
+working.entities.0.name
+working.artifacts.draft
+```
+
 Examples:
 
 ```
 inputs.file_path
 vars.document_text
 outputs.summary
+frame.goal
+working.risks
+output.result_type
 ```
 
 ---
@@ -564,10 +603,36 @@ outputs.summary
 The following rules apply:
 
 1. Steps cannot modify `inputs`.
-2. Steps may write only to `vars` or `outputs`.
-3. Each target field should be written once.
-4. Outputs declared in the skill must be produced by a step.
-5. Steps may consume values produced by earlier steps.
+2. Steps may write to `vars` or `outputs` (legacy), or `working`, `output`, `extensions` (CognitiveState v1).
+3. Steps cannot write to `frame` (frozen) or `trace` (engine-managed).
+4. Each target field should be written once (unless a merge strategy is declared).
+5. Outputs declared in the skill must be produced by a step.
+6. Steps may consume values produced by earlier steps.
+
+### Merge Strategies (CognitiveState v1)
+
+When multiple steps write to the same target, a merge strategy may be declared
+in `step.config.merge_strategy`:
+
+| Strategy | Behavior |
+|----------|----------|
+| `overwrite` | Default. Error on duplicate target. |
+| `append` | Extends list targets via concatenation. |
+| `deep_merge` | Recursively merges dict targets. |
+| `replace` | Unconditionally overwrites, no error. |
+
+Example:
+
+```yaml
+- id: collect_risks
+  uses: analysis.risk.extract
+  config:
+    merge_strategy: append
+  input:
+    text: vars.document_text
+  output:
+    risks: working.risks
+```
 
 Execution order is determined by **data dependencies**.