feat: document resource type

.cursor/skills/examining-ado-operations/SKILL.md

@@ -16,18 +16,18 @@ Structured workflow for understanding what an operation did, which space it ran
 on, and whether measurements and results look healthy.
 
 - Run all commands from the **repository root** with `uv run`.
-- Write the report to `reports/<ado_context_name>/` (create the directory if
-  needed)
-  - where `ado_context_name` is the **active ado metastore context**
-    (`uv run ado context`)
-- Write the report as `<OPERATIONID>_<YYYY-MM-DD>_report.md`
+- The report produced by this skill is stored as the `content` of a
+  `document` resource in the active ado metastore context (see
+  [Producing a report](#producing-a-report)).
 
 **Related skills**:
 
 - For CLI verification and command spelling, see
   [using-ado-cli](../using-ado-cli/SKILL.md).
 - For metastore filtering, schemas see
   [query-ado-data](../query-ado-data/SKILL.md).
+- For creating document resources that store reports, see
+  [resource-yaml-creation — Document](../resource-yaml-creation/SKILL.md#document).
 - For a project/context wide view (all spaces and operations), see
   [examining-ado-project](../examining-ado-project/SKILL.md).
 
@@ -125,11 +125,20 @@ failure. In this case:
 
 If the operation is finished,
 
-- Check if there is an existing report for this operation in
-  `reports/<ado_context_name>/`
-- If yes, check if that report indicated the operation was finished
-  - If yes, ask the user if they want to replace it with a new report
-  - If no, continue with creating new report
+- Query the metastore for an existing document linked to this operation:
+
+  ```bash
+  uv run ado get document -q 'config.relatedResources=OPERATION_ID'
+  ```
+
+  If a document is found, retrieve its metadata (name, created timestamp) and
+  fetch its `content` (`uv run ado get document DOCUMENT_ID -o yaml`) to check
+  if that report indicated the operation was finished.
+  - If yes, ask the user whether to replace it with a new report. If they
+    agree, delete the existing document (`uv run ado delete document
+    DOCUMENT_ID`) once the new report has been created. See
+    [resource-yaml-creation — Document](../resource-yaml-creation/SKILL.md#document).
+  - If no, continue with creating a new report.
 
 ### Step 3: Review the operator
 
@@ -321,6 +330,10 @@ Structure the report as:
    distributions
 5. **Next Steps**: A plan for the next research steps to take using ado.
 
+Store the report as a document resource (see
+[resource-yaml-creation — Document](../resource-yaml-creation/SKILL.md#document)).
+Set `relatedResources` to the operation id and the input space ids from step 1.
+
 ## Troubleshooting
 
 ### Number points sampled is greater than the number of entities measured by operation

.cursor/skills/examining-ado-project/SKILL.md

@@ -15,6 +15,9 @@ related metadata in the ado project associated to the active context.
 
 - Run all commands from the **repository root** with `uv run` (see
   [using-ado-cli](../using-ado-cli/SKILL.md)).
+- The report produced by this skill is stored as the `content` of a
+  `document` resource in the active ado metastore context (see
+  [Producing a report](#producing-a-report)).
 - See
   [projects and contexts](../../../docs/resources/metastore.md#contexts-and-projects)
   for details on what projects and contexts are
@@ -24,6 +27,8 @@ related metadata in the ado project associated to the active context.
 
 - Prefer metastore listing and YAML dumps before heavy `uv run ado show` data
   pulls; see [query-ado-data](../query-ado-data/SKILL.md).
+- For creating document resources that store reports, see
+  [resource-yaml-creation — Document](../resource-yaml-creation/SKILL.md#document).
 - For one space in depth:
   [examining-discovery-spaces](../examining-discovery-spaces/SKILL.md).
 - For one operation in depth:
@@ -209,26 +214,57 @@ Optionally complement with one-hop links:
 uv run ado show related space SPACE_ID
 ```
 
-## 4. Report template
-
-Write a concise markdown report
-
-- Write the report to `reports/<ado_context_name>/` (create the directory if
-  needed), where `ado_context_name` is the **active ado metastore context**
-  (`uv run ado context`).
-- Write the report as `project_<YYYY-MM-DD>_report.md`.
-- If a report already exists, check whether there has been meaningful activity
-  since it was written before replacing it:
-  1. Run `uv run ado get spaces --details` and
-     `uv run ado get operations --details` and note the age of the most recent
-     resource.
-  2. If the most recent resource is **younger** than the date of the existing
-     report, there has been new activity — proceed to write a new report.
-  3. If not, ask the user whether they want to replace it.
-  4. If finer-grained confirmation is needed, fetch the YAML of the most recent
-     space or operation
-     (`uv run ado get space SPACE_ID -o yaml --output-file SPACE_ID.yaml`, or
-     the same pattern for `operation`) and read its `creationTimestamp` field.
+## 4. Check for existing report
+
+The project report is stored as a `document` resource whose `metadata.name` is
+ `project_report`. There **may** be zero, one, or
+many documents with that name — each has a unique identifier. If several match,
+the **current** report is the most recently created one.
+
+Query the metastore:
+
+```bash
+uv run ado get document -q 'config.metadata.name=project_report' --details
+```
+
+If matches exist:
+
+1. Identify the **current** document (newest by creation timestamp from
+   `--details` or from document YAML `created` / status timestamps). Fetch its
+   `content` (`uv run ado get document DOCUMENT_ID -o yaml`).
+2. Check whether there has been meaningful activity since the current report
+   was written:
+   1. Run `uv run ado get spaces --details` and
+      `uv run ado get operations --details` and note the age of the most recent
+      resource.
+   2. If the most recent resource is **younger** than the current document's
+      creation timestamp, there has been new activity — proceed toward writing
+      a new report.
+   3. If not, ask the user whether they want to write a new report anyway. If
+      they decline, stop and use/refer to the current document id.
+   4. If finer-grained confirmation is needed, fetch the YAML of the most recent
+      space or operation (`uv run ado get space SPACE_ID -o yaml --output-file
+      SPACE_ID.yaml`, or the same pattern for `operation`) and read its
+      `creationTimestamp` field.
+3. Before creating a new report when a current one exists, **ask** whether to:
+   - **Keep history** — leave existing `project_report` document(s); create
+     another with the same name.
+   - **Replace** — delete the current document
+     (`uv run ado delete document DOCUMENT_ID`), then create the new one.
+     See
+     [resource-yaml-creation — Document](../resource-yaml-creation/SKILL.md#document).
+   Do not auto-delete; do not assume history must be kept.
+
+## Producing a report
+
+Write a concise markdown report. Store it as the `content` field of a
+`document` resource (see
+[resource-yaml-creation — Document](../resource-yaml-creation/SKILL.md#document)).
+
+- Set `metadata.name` to `project_report`.
+- Set `metadata.description` to include today's date, e.g.
+  `Project overview as of YYYY-MM-DD`.
+- Omit `relatedResources` (or leave empty).
 
 ### Project summary
 

.cursor/skills/examining-discovery-spaces/SKILL.md

@@ -15,18 +15,18 @@ Structured workflow for understanding what a discoveryspace contains, how
 covered its entity space is, and what data has been collected.
 
 - Run all commands from the **repository root** with `uv run`.
-- Write the report to `reports/<ado_context_name>/` (create the directory if
-  needed)
-  - where `ado_context_name` is the **active ado metastore context**
-    (`uv run ado context`)
-- Write the report as `<SPACEID>_<YYYY-MM-DD>_report.md`
+- The report produced by this skill is stored as the `content` of a
+  `document` resource in the active ado metastore context (see
+  [Producing a report](#producing-a-report)).
 
 **Related skills**:
 
 - For CLI verification and command spelling, see
   [using-ado-cli](../using-ado-cli/SKILL.md).
 - For metastore filtering and schemas, see
   [query-ado-data](../query-ado-data/SKILL.md).
+- For creating document resources that store reports, see
+  [resource-yaml-creation — Document](../resource-yaml-creation/SKILL.md#document).
 - For examining operations run on a space, see
   [examining-ado-operations](../examining-ado-operations/SKILL.md).
 - For a project/context wide view (all spaces and operations), see
@@ -150,13 +150,24 @@ uv run ado show related space SPACE_ID
 
 ### Step 3: Check for existing report
 
-- Check if there is an existing report for this space in
-  `reports/<ado_context_name>/`
-- If yes, check if either of the following are true:
-  - New operations have been run on space since report
+- Query the metastore for an existing document linked to this space:
+
+  ```bash
+  uv run ado get document -q 'config.relatedResources=SPACE_ID'
+  ```
+
+  If a document is found, retrieve its metadata (name, created timestamp) and
+  fetch its `content` (`uv run ado get document DOCUMENT_ID -o yaml`) to
+  compare against current state.
+- If a document is found, check if either of the following are true:
+  - New operations have been run on the space since the document was created
   - The number of measured entities has increased
-- If neither of above are true, ask the user if they want to write a new report
-  or use existing
+- If yes to either, ask the user whether to replace it with a new report. If
+  they agree, delete the existing document (`uv run ado delete document
+  DOCUMENT_ID`) once the new report has been created. See
+  [resource-yaml-creation — Document](../resource-yaml-creation/SKILL.md#document).
+- If neither of the above are true, ask the user if they want to write a new
+  report or use the existing one
   - As nothing has changed, the only purpose of creating a new report is if a
     different agent is being used
 
@@ -201,7 +212,7 @@ understand what each operation did and what it produced.
 Note: Do not analyze the data in the operations, or do detailed diagnoses. Just
 enough for summary.
 
-## Producing a Report
+## Producing a report
 
 Structure the report as:
 
@@ -217,3 +228,8 @@ Structure the report as:
 4. **Data summary** – distributions of measured properties, notable performers,
    outliers, correlations
 5. **Related operations** – which operations ran on this space and their status
+
+Store the report as a document resource (see
+[resource-yaml-creation — Document](../resource-yaml-creation/SKILL.md#document)).
+Set `relatedResources` to the space id and the related operation ids from
+step 2.

.cursor/skills/resource-yaml-creation/SKILL.md

@@ -2,10 +2,10 @@
 name: resource-yaml-creation
 description: |
   Guidance for creating ado resource YAML files (discoveryspace, operation,
-  actuatorconfiguration, samplestore). Covers metadata conventions, dynamic
-  reference resolution with --use-latest/--with/--set, space design principles,
-  avoiding duplicate resources, and validation. Use when creating or editing
-  any ado resource YAML file.
+  actuatorconfiguration, samplestore, document). Covers metadata conventions,
+  dynamic reference resolution with --use-latest/--with/--set, space design
+  principles, avoiding duplicate resources, document reports, and validation.
+  Use when creating or editing any ado resource YAML file.
 ---
 
 # Creating ado Resource YAML Files
@@ -33,7 +33,7 @@ metadata:
 - `name` and `description` are shown by `ado get --details`
 - `labels` support filtering: `uv run ado get spaces --label project=my_project`
 - `--filter` supports path-based filtering across any field:
-  `uv run ado get spaces --filter "metadata.name=my_space"`
+  `uv run ado get spaces --filter 'config.metadata.name=my_space'`
 
 ## Dynamic Reference Resolution
 
@@ -194,6 +194,52 @@ shared measurement history.
 uv run ado create samplestore -f samplestore.yaml
 ```
 
+### Document
+
+Use `document` resources to persist markdown or HTML reports in the metastore.
+Set `contentType` to `markdown` (default) or `html`. See the
+[document resource documentation](../../../docs/resources/document.md).
+Examining skills store their reports this way: put the body in `content`,
+optionally set `contentType`, and list related resource identifiers in
+`relatedResources`.
+
+```yaml
+# <descriptive>_document.yaml  (temp file, not committed)
+metadata:
+  name: "<descriptive name>"
+  description: "<one-line summary>"
+contentType: markdown  # or html
+content: |
+  <full report text>
+relatedResources:
+  - <related resource ids>
+```
+
+```bash
+uv run ado create document -f <descriptive>_document.yaml
+uv run ado delete document DOCUMENT_ID
+```
+
+Validate with `uv run ado create document -f FILE --dry-run` before creating.
+
+**Querying existing documents** (paths are under `config.`; string candidates
+must be single-quoted — see [query-ado-data](../query-ado-data/SKILL.md)):
+
+```bash
+# By related resource id (array containment — no [*] subscript)
+uv run ado get document -q 'config.relatedResources=RESOURCE_ID'
+
+# By metadata name
+uv run ado get document -q 'config.metadata.name=NAME'
+```
+
+Fetch a document's body with
+`uv run ado get document DOCUMENT_ID -o yaml`.
+
+When replacing a report, delete the existing document only after the user
+agrees and the new report has been created (or immediately before creating the
+replacement, if the skill's replace policy says so).
+
 ## Related Resources
 
 - [using-ado-cli](../using-ado-cli/SKILL.md) — CLI command syntax and shortcuts

AGENTS.md

@@ -20,6 +20,7 @@ These guidelines apply to all code development in the ado codebase.
     - samplestore
     - datacontainer
     - actuatorconfiguration
+    - document
   - **modules/actuators**: defines actuators, custom experiments, and their
     associated management code (plugins, registry)
   - **modules/operators**: defines operators and their associated management

ado/cli/commands/create.py

@@ -22,6 +22,7 @@
 )
 from ado.cli.resources.context.create import create_context
 from ado.cli.resources.discovery_space.create import create_discovery_space
+from ado.cli.resources.document.create import create_document
 from ado.cli.resources.operation.create import create_operation
 from ado.cli.resources.sample_store.create import create_sample_store
 from ado.cli.utils.input.parsers import (
@@ -239,6 +240,7 @@ def create_resource(
         AdoCreateSupportedResourceTypes.ACTUATOR_CONFIGURATION: create_actuator_configuration,
         AdoCreateSupportedResourceTypes.CONTEXT: create_context,
         AdoCreateSupportedResourceTypes.DISCOVERY_SPACE: create_discovery_space,
+        AdoCreateSupportedResourceTypes.DOCUMENT: create_document,
         AdoCreateSupportedResourceTypes.SAMPLE_STORE: create_sample_store,
         AdoCreateSupportedResourceTypes.OPERATION: create_operation,
     }

ado/cli/commands/delete.py

@@ -14,6 +14,7 @@
 from ado.cli.resources.context.delete import delete_context
 from ado.cli.resources.data_container.delete import delete_data_container
 from ado.cli.resources.discovery_space.delete import delete_discovery_space
+from ado.cli.resources.document.delete import delete_document
 from ado.cli.resources.operation.delete import delete_operation
 from ado.cli.resources.sample_store.delete import delete_sample_store
 from ado.cli.utils.input.parsers import enum_choice_with_plural_parser
@@ -220,6 +221,7 @@ def delete_resource(
         AdoDeleteSupportedResourceTypes.CONTEXT: delete_context,
         AdoDeleteSupportedResourceTypes.DATA_CONTAINER: delete_data_container,
         AdoDeleteSupportedResourceTypes.DISCOVERY_SPACE: delete_discovery_space,
+        AdoDeleteSupportedResourceTypes.DOCUMENT: delete_document,
         AdoDeleteSupportedResourceTypes.SAMPLE_STORE: delete_sample_store,
         AdoDeleteSupportedResourceTypes.OPERATION: delete_operation,
     }

ado/cli/commands/describe.py

@@ -16,6 +16,7 @@
 from ado.cli.models.types import AdoDescribeSupportedResourceTypes
 from ado.cli.resources.data_container.describe import describe_data_container
 from ado.cli.resources.discovery_space.describe import describe_discovery_space
+from ado.cli.resources.document.describe import describe_document
 from ado.cli.resources.experiment.describe import describe_experiment
 from ado.cli.utils.generic.common import get_effective_resource_id
 from ado.cli.utils.input.parsers import enum_choice_with_plural_parser
@@ -96,6 +97,9 @@ def describe_resource(
 
     # Describe an experiment, optionally with actuator prefix
     ado describe experiment <actuator-id>.<experiment-id>
+
+    # Describe a document (markdown in-terminal; HTML opens in browser)
+    ado describe document <document-id>
     """
     ado_configuration: AdoConfiguration = ctx.obj
 
@@ -141,6 +145,7 @@ def describe_resource(
     method_mapping = {
         AdoDescribeSupportedResourceTypes.DATA_CONTAINER: describe_data_container,
         AdoDescribeSupportedResourceTypes.DISCOVERY_SPACE: describe_discovery_space,
+        AdoDescribeSupportedResourceTypes.DOCUMENT: describe_document,
         AdoDescribeSupportedResourceTypes.EXPERIMENT: describe_experiment,
     }
 

ado/cli/commands/edit.py

@@ -21,6 +21,7 @@
 )
 from ado.cli.resources.data_container.edit import edit_data_container
 from ado.cli.resources.discovery_space.edit import edit_discovery_space
+from ado.cli.resources.document.edit import edit_document
 from ado.cli.resources.operation.edit import edit_operation
 from ado.cli.resources.sample_store.edit import edit_sample_store
 from ado.cli.utils.input.parsers import enum_choice_with_plural_parser
@@ -132,6 +133,7 @@ def edit_resource(
         AdoEditSupportedResourceTypes.ACTUATOR_CONFIGURATION: edit_actuator_configuration,
         AdoEditSupportedResourceTypes.DATA_CONTAINER: edit_data_container,
         AdoEditSupportedResourceTypes.DISCOVERY_SPACE: edit_discovery_space,
+        AdoEditSupportedResourceTypes.DOCUMENT: edit_document,
         AdoEditSupportedResourceTypes.SAMPLE_STORE: edit_sample_store,
         AdoEditSupportedResourceTypes.OPERATION: edit_operation,
     }