donna 0.2.0__py3-none-any.whl → 0.2.2__py3-none-any.whl

donna/artifacts/rfc/work/create.md

@@ -0,0 +1,120 @@
+
+# Create a Request for Change
+
+```toml donna
+kind = "donna.lib.workflow"
+start_operation_id = "start"
+```
+
+This workflow creates a Request for Change (RFC) document based on a description of the problem or the required changes.
+
+## Start Work
+
+```toml donna
+id = "start"
+kind = "donna.lib.request_action"
+fsm_mode = "start"
+```
+
+1. Read the specification `{{ donna.lib.view("donna:rfc:specs:request_for_change") }}` if you haven't done it yet.
+2. Read the specification `{{ donna.lib.view("donna:usage:artifacts") }}` if you haven't done it yet.
+3. `{{ donna.lib.goto("ensure_work_description_exists") }}`
+
+## Ensure work description exists
+
+```toml donna
+id = "ensure_work_description_exists"
+kind = "donna.lib.request_action"
+```
+
+At this point, you SHOULD have a clear description of the problem in your context. I.e. you know what you need to do in this workflow.
+
+1. If you have a problem description in your context, `{{ donna.lib.goto("prepare_rfc_artifact") }}`.
+2. If you have no problem description in your context, but you know it is in one of `{{ donna.lib.list("session:**") }}` artifacts, find and view it. Then `{{ donna.lib.goto("prepare_rfc_artifact") }}`.
+3. If you have no problem description in your context, and you don't know where it is, ask the developer to provide it. After you get the problem description, `{{ donna.lib.goto("prepare_rfc_artifact") }}`.
+
+## Prepare RFC artifact
+
+```toml donna
+id = "prepare_rfc_artifact"
+kind = "donna.lib.request_action"
+```
+
+1. If the name of the artifact is not specified explicitly, assume it to be `session:rfc:<short-problem-related-identifier>`, where `<short-problem-related-identifier>` MUST be unique within the session.
+2. Save the next template into the artifact, replace `<variables>` with appropriate values.
+
+```
+# <Title>
+
+<short description of the proposed change>
+
+## Original description
+
+<original description of the requested changes from the developer or parent workflow>
+
+## Formal description
+
+## Goals
+
+## Objectives
+
+## Constraints
+
+## Requirements
+
+## Acceptance criteria
+
+## Solution
+
+## Verification
+
+## Deliverables
+
+## Action items
+```
+
+3. `{{ donna.lib.goto("initial_fill") }}`
+
+## Initial Fill
+
+```toml donna
+id = "initial_fill"
+kind = "donna.lib.request_action"
+```
+
+1. Read the specification `{{ donna.lib.view("donna:rfc:specs:request_for_change") }}` if you haven't done it yet.
+2. Analyze the project if needed to understand the context of the requested change.
+3. Based on the problem description you have, fill in all sections of the RFC draft artifact.
+4. `{{ donna.lib.goto("review_rfc_format") }}`
+
+## Review RFC Format
+
+```toml donna
+id = "review_rfc_format"
+kind = "donna.lib.request_action"
+```
+
+1. List mismatches between the RFC artifact and the RFC specification `{{ donna.lib.view("donna:rfc:specs:request_for_change") }}`.
+2. For each mismatch, make necessary edits to the RFC draft artifact to ensure compliance with the RFC specification.
+3. `{{ donna.lib.goto("review_rfc_content") }}`
+
+## Review RFC Content
+
+```toml donna
+id = "review_rfc_content"
+kind = "donna.lib.request_action"
+```
+
+1. Read the RFC document and identify any gaps, inconsistencies, or areas for improvement in the content in accordance with the current project context. Use `{{ donna.lib.view("donna:research:work:research") }}` workflow if you need to make a complex decision.
+2. Make necessary edits to the RFC draft artifact to address identified issues.
+3. If there were changes made on this step or the previous `review_rfc_format` step `{{ donna.lib.goto("review_rfc_format") }}`.
+4. If no changes were made, `{{ donna.lib.goto("finish") }}`.
+
+## Complete Draft
+
+```toml donna
+id = "finish"
+kind = "donna.lib.finish"
+```
+
+RFC draft is complete and ready for planning or review.

donna/artifacts/rfc/work/do.md

@@ -0,0 +1,109 @@
+
+# Do Request For Change work
+
+```toml donna
+kind = "donna.lib.workflow"
+start_operation_id = "estimate_complexity"
+```
+
+This workflow uses a description of a problem or changes required from the developer or parent workflow to:
+
+1. Create a Request for Change (RFC) artifact.
+2. Plan the work required to implement the RFC.
+3. Execute the planned work.
+
+## Estimate complexity
+
+```toml donna
+id = "estimate_complexity"
+kind = "donna.lib.request_action"
+```
+
+1. If the developer or parent workflow explicitly specified that the work is complex, `{{ donna.lib.goto("create_rfc") }}`.
+2. If the developer or parent workflow explicitly specified that the work is simple, `{{ donna.lib.goto("fast_planning") }}`.
+3. Make a rough estimate of the complexity of the requested changes.
+4. If the complexity is small, `{{ donna.lib.goto("fast_planning") }}`.
+5. Otherwise, `{{ donna.lib.goto("create_rfc") }}`.
+
+Examples of changes with small complexity:
+
+- A single file edit with clear instructions.
+- A small addition to an existing function or class.
+- A minor configuration change.
+- A small documentation update.
+- A simple bug fix with a known solution.
+
+## Fast planning
+
+```toml donna
+id = "fast_planning"
+kind = "donna.lib.request_action"
+```
+
+1. Draft a simple plan to implement the requested changes directly, without creating a formal RFC artifact.
+2. `{{ donna.lib.goto("plan_rfc_work") }}`.
+
+## Create RFC
+
+```toml donna
+id = "create_rfc"
+kind = "donna.lib.request_action"
+fsm_mode = "start"
+```
+
+1. Choose a workflow to create an RFC artifact.
+2. Run the chosen workflow.
+2. After completing the workflow `{{ donna.lib.goto("plan_rfc_work") }}`.
+
+## Plan RFC work
+
+```toml donna
+id = "plan_rfc_work"
+kind = "donna.lib.request_action"
+```
+
+1. Choose the workflow to plan the work required to implement the RFC created in the previous step.
+2. Run the chosen workflow.
+3. Ensure you know the workflow id created in the previous step (default is `session:execute_rfc` if not specified).
+4. After completing the workflow `{{ donna.lib.goto("execute_rfc_work") }}`.
+
+## Execute RFC work
+
+```toml donna
+id = "execute_rfc_work"
+kind = "donna.lib.request_action"
+```
+
+1. Run the workflow created by the plan step (default: `session:execute_rfc`) and complete it.
+2. After completing the workflow `{{ donna.lib.goto("polish_changes") }}`.
+
+## Polish changes
+
+```toml donna
+id = "polish_changes"
+kind = "donna.lib.request_action"
+```
+
+1. Find the workflow to polish the changes made.
+2. Run the chosen workflow if you found one.
+3. `{{ donna.lib.goto("log_changes") }}`.
+
+## Log changes
+
+```toml donna
+id = "log_changes"
+kind = "donna.lib.request_action"
+```
+
+1. Find the workflow to log the changes made in the scope of this RFC.
+2. Run the chosen workflow if you found one.
+3. `{{ donna.lib.goto("finish") }}`.
+
+## Finish
+
+```toml donna
+id = "finish"
+kind = "donna.lib.finish"
+```
+
+RFC workflow execution completed. Report the outcome to the developer.

donna/artifacts/rfc/work/plan.md

@@ -0,0 +1,68 @@
+
+# Plan work on Request For Change
+
+```toml donna
+kind = "donna.lib.workflow"
+start_operation_id = "start"
+```
+
+This workflow plans the work required to implement a specified Request for Change (RFC). The result of this workflow is a new workflow in the `session:*` world with detailed steps to implement the RFC.
+
+## Start Work
+
+```toml donna
+id = "start"
+kind = "donna.lib.request_action"
+fsm_mode = "start"
+```
+
+1. Read the RFC that the developer or parent workflow wants you to implement.
+2. Read the specification `{{ donna.lib.view("donna:usage:artifacts") }}` if you haven't done it yet.
+2. `{{ donna.lib.goto("prepare_workflow_artifact") }}`
+
+## Prepare workflow artifact
+
+```toml donna
+id = "prepare_workflow_artifact"
+kind = "donna.lib.request_action"
+```
+
+1. If the name of the artifact is not specified explicitly, assume it to `session:plans:<short-id-equal-to-rfc-slug>`.
+2. Create a workflow with the next operations:
+   - Start
+   - A step for each action point in the RFC, ordered to minimize dependencies between steps and introduce changes incrementally.
+   - (`id="review_changes"`) A gate step to start reviewing the changes.
+   - A gate step to start reviewing the deliverables.
+   - A step per deliverable to check if it exists and is correct. If the deliverable is missing or incorrect, the step MUST specify how to fix it and `goto` to the `review_changes` step.
+   - A gate step to start verification.
+   - A step for each verification statement to check it. If the statement is not satisfied, the step MUST specify how to fix it and `goto` to the `review_changes` step.
+   - A finish step.
+3. `{{ donna.lib.goto("review_workflow") }}`
+
+## Review workflow
+
+```toml donna
+id = "review_workflow"
+kind = "donna.lib.request_action"
+```
+
+For each of the steps in the workflow you created:
+
+1. If the step can fail, add instructions on how to fix the issue and `goto` to the appropriate step.
+2. If the step requires both research and implementation, split it into two steps: research step and implementation step.
+3. If the step required editing multiple artifacts (multiple files, multiple functions, etc.), split it into multiple steps, one per change required.
+4. If the step is too big or complex, split it into multiple smaller steps.
+
+After all steps are reviewed:
+
+1. If the changes were introduced, `{{ donna.lib.goto("review_workflow") }}`.
+2. If no changes were introduced, `{{ donna.lib.goto("finish") }}`.
+
+## Finish
+
+```toml donna
+id = "finish"
+kind = "donna.lib.finish"
+```
+
+RFC work plan finalized. Ready to execute the planned workflow.

donna/artifacts/usage/artifacts.md

@@ -18,6 +18,8 @@ The text artifact has a source and one or more rendered representations, produce
 
 To change the artifact, developers and agents edit its source.
 
+When you need a scratch file for artifact-related work, use `donna -p <protocol> artifacts tmp '<slug>.<extension>'` to create a temporary file in the workspace temp directory.
+
 To get information from the artifact, developers, agents and Donna view one of its representations (typically via the view rendering mode).
 
 **If you need an information from the artifact, you MUST view its representation**. Artifact sources are only for editing.
@@ -26,19 +28,29 @@ Read the specification `{{ donna.lib.view("donna:usage:cli") }}` to learn how to
 
 ## Source Format and Rendering
 
-The source of the text artifact is a Jinja2-template of Markdown document.
+The source of the text artifact is a Jinja2 template of a Markdown document.
 
 When rendering the artifact, Donna processes the Jinja2 template with a predefined context (at minimum `render_mode` and `artifact_id`, and optionally `current_task`/`current_work_unit` during workflow execution), then renders the resulting Markdown content into the desired representation based on the selected rendering mode.
 
-**Artifact source should not use Jinja2 inheretance features** like `{{ "{% extends %}" }}` and `{{ "{% block %}" }}`.
+**Artifact source should not use Jinja2 inheritance features** like `{{ "{% extends %}" }}` and `{{ "{% block %}" }}`.
 
 Donna provides a set of special directives that can and MUST be used in the artifact source to enhance its behavior. Some of these directives are valid for all artifacts, some are valid only for specific section kinds.
 
 Here are some examples:
 
-- `{{ "{{ donna.lib.view(<artifact-id>) }}" }}` — references another artifact. In `view`/`execute` modes it renders an exact CLI command to view the artifact; in `analysis` mode it renders a `$$donna ... $$` marker used for internal parsing.
+- `{{ "{{ donna.lib.view(<artifact-id-pattern>) }}" }}` — references another artifact (supports `*` and `**` wildcard patterns). In `view`/`execute` modes it renders an exact CLI command to view the artifact; in `analysis` mode it renders a `$$donna ... $$` marker used for internal parsing.
+- `{{ "{{ donna.lib.list(<artifact-id-pattern>) }}" }}` — references artifact listing by pattern (supports `*` and `**` wildcard patterns). In `view`/`execute` modes it renders an exact CLI command to list artifacts; in `analysis` mode it renders a `$$donna ... $$` marker used for internal parsing.
 - `{{ "{{ donna.lib.goto(<workflow-operation-id>) }}" }}` — references the next workflow operation to execute. In `view`/`execute` modes it renders an exact CLI command to advance the workflow; in `analysis` mode it renders a `$$donna goto ... $$` marker used to extract workflow transitions.
 
+## Jinja2 rendering
+
+Donna allows all of Jinja2 expressions in artifact sources, except inheritance-related once: `{{ "{% extends %}" }}` , `{{ "{% block %}" }}`, etc.
+
+Donna intentionally hides some parts of the source in the rendered output, but they remain visible in source views (for example, in `artifacts fetch` output or on GitHub):
+
+- fenced code blocks with the `donna` marker (they contain technical information for the Donna, not information for the agent).
+- Jinja2 comments like `{{ "{# ... #}" }}`.
+
 ## Rendering artifacts
 
 Donna renders the same artifact source into different representations depending on the rendering mode. The mode is internal to Donna (users do not select it directly) and controls how directives are expanded and which metadata is included.
@@ -51,11 +63,11 @@ Donna renders the same artifact source into different representations depending
 
 Technically, any valid Markdown document is a valid text artifact.
 
-However, Donna assignes special meaning to some elements of the Markdown document to provide enhanced behavior and capabilities.
+However, Donna assigns special meaning to some elements of the Markdown document to provide enhanced behavior and capabilities.
 
 ### Sections
 
-Artifact is devided into multiple sections:
+Artifact is divided into multiple sections:
 
 - H1 header and all text till the first H2 header is considered the `head section` of the artifact.
 - Each H2 header and all text till the next H2 header (or end of document) is considered a `tail section` of the artifact.
@@ -88,7 +100,7 @@ The configuration block properties format is `property1 property2=value2 propert
 
 The content of the block is parsed according to the primary format and interpreted according its properties.
 
-Configuration blocks are parsed by Donna and removed from rendered Markdown representations; they remain in the source for editing and inspection (e.g., via `artifacts fetch` or the repository file).
+Configuration blocks are parsed by Donna and removed from rendered Markdown representations (see "Jinja2 rendering"); they remain in the source for editing and inspection (e.g., via `artifacts fetch` or the repository file).
 
 Fences without `donna` keyword are considered regular code blocks and have no special meaning for Donna.
 
@@ -101,6 +113,14 @@ When a section contains multiple configuration blocks, Donna merges them in docu
 - The merge is shallow: if a key maps to a nested object, a later block replaces the whole value (there is no deep merge).
 - Config blocks in subsections (H3 and below) belong to their parent H2 tail section and are merged into that section's configuration.
 
+### Artifact Tags
+
+Artifacts can include semantic tags via a `tags` field in the section configuration. Tags are a list of strings and default to an empty list `[]` when omitted.
+
+Tags are used for deterministic artifact filtering and discovery (for example, via `donna -p <protocol> artifacts list ... --tag <tag>`). Tags are typically attached to the primary section and describe the artifact as a whole.
+
+The canonical list of standard tags is documented in `donna:intro`.
+
 ## Section Kinds, Their Formats and Behaviors
 
 ### Header section
@@ -150,7 +170,9 @@ kind = "donna.lib.request_action"
 
 #### Kinds of Workflow Operations
 
-1. `donna.lib.request_action` operation kind indicates that Donna will request the agent to perform some action.
+##### `donna.lib.request_action`
+
+`donna.lib.request_action` operation kind indicates that Donna will request the agent to perform some action.
 
 The content of the tail section is the text instructions for the agent on what to do.
 
@@ -168,7 +190,9 @@ Here may be any additional instructions, requirements, notes, references, etc.
 
 **The body of the operation MUST contain a neat strictly defined algorithm for the agent to follow.**
 
-2. `donna.lib.run_script` operation kind executes a script from the operation body without agent/user interaction.
+##### `donna.lib.run_script`
+
+`donna.lib.run_script` operation kind executes a script from the operation body without agent/user interaction.
 
 The body of the operation MUST include exactly one fenced code block whose info string includes `<language> donna script`.
 Any other text in the operation body is ignored.
@@ -209,7 +233,25 @@ Routing rules:
 When `save_stdout_to` and/or `save_stderr_to` are set, the operation stores captured output in the task context
 under the specified variable names.
 
-3. `donna.lib.finish` operation kind indicates that the workflow is finished.
+##### `donna.lib.output`
+
+`donna.lib.output` operation kind emits its body as an output cell and then continues to the configured next step.
+
+The body of the operation is rendered as an output cell during execution.
+
+Configuration options:
+
+```toml
+id = "<operation_id>"
+kind = "donna.lib.output"
+next_operation_id = "<next_operation_id>"  # required
+```
+
+##### `donna.lib.finish`
+
+`donna.lib.finish` operation kind indicates that the workflow is finished.
+
+The body of the operation is rendered as an output cell before the workflow completes.
 
 Each possible path through the workflow MUST end with this operation kind.
 
@@ -219,6 +261,7 @@ Donna provides multiple directives that MUST be used in the artifact source to e
 
 Here they are:
 
-1. `{{ "{{ donna.lib.view(<full-artifact-id>) }}" }}` — references another artifact. In `view`/`execute` modes it renders an exact CLI command to view the artifact; in `analysis` mode it renders a `$$donna ... $$` marker.
-2. `{{ "{{ donna.lib.goto(<workflow-operation-id>) }}" }}` — references the next workflow operation to execute. In `view`/`execute` modes it renders an exact CLI command to advance the workflow; in `analysis` mode it renders a `$$donna goto ... $$` marker used for transition extraction.
-3. `{{ "{{ donna.lib.task_variable(<variable_name>) }}" }}` — in `view` mode renders a placeholder note about task-variable substitution, in `execute` mode renders the actual task-context value (or an explicit error marker if missing), and in `analysis` mode renders a `$$donna task_variable ... $$` marker.
+1. `{{ "{{ donna.lib.view(<artifact-id-pattern>) }}" }}` — references another artifact (supports `*` and `**` wildcard patterns). In `view`/`execute` modes it renders an exact CLI command to view the artifact; in `analysis` mode it renders a `$$donna ... $$` marker.
+2. `{{ "{{ donna.lib.list(<artifact-id-pattern>) }}" }}` — references artifact listing by pattern (supports `*` and `**` wildcard patterns). In `view`/`execute` modes it renders an exact CLI command to list artifacts; in `analysis` mode, it renders a `$$donna ... $$` marker.
+3. `{{ "{{ donna.lib.goto(<workflow-operation-id>) }}" }}` — references the next workflow operation to execute. In `view`/`execute` modes it renders an exact CLI command to advance the workflow; in `analysis` mode, it renders a `$$donna goto ... $$` marker used for transition extraction.
+4. `{{ "{{ donna.lib.task_variable(<variable_name>) }}" }}` — in `view` mode renders a placeholder note about task-variable substitution, in `execute` mode renders the actual task-context value (or an explicit error marker if missing), and in `analysis` mode renders a `$$donna task_variable ... $$` marker.

donna/artifacts/usage/cli.md

@@ -4,7 +4,7 @@
 kind = "donna.lib.specification"
 ```
 
-This document describes how agents MUST use Donna to manage and perform their workflows.
+This document describes how agents MUST use Donna CLI to manage and perform their workflows.
 
 **Agents MUST follow the instructions and guidelines outlined in this document precisely.**
 
@@ -12,66 +12,141 @@ This document describes how agents MUST use Donna to manage and perform their wo
 
 `donna` is a CLI tool that helps manage the work of AI agents like OpenAI Codex.
 
-It is designed to invert control flow: instead of agents deciding what to do next, the `donna` tells agents what to do next by following predefined workflows.
+It is designed to invert control flow: instead of agents deciding what to do next, the Donna tells agents what to do. The tool achieves this by following predefined workflows that describe how to perform various tasks. One may look at workflows as hierarchical state machines (HSM) that guide agents through complex processes step by step.
 
-The core idea is that most high-level workflows are more algorithmic than it may seem at first glance. For example, it may be difficult to fix a particular type issue in the codebase, but the overall process of polishing the codebase is quite linear:
+The core idea is that most high-level workflows are more algorithmic than it may seem at first glance. For example, it may be difficult to fix a particular problem in the codebase, but the overall process of polishing it is quite linear:
 
-1. Ensure all tests pass.
-2. Ensure the code is formatted correctly.
-3. Ensure there are no linting errors.
+1. Run tests, if they fail, fix the problems.
+2. Format the code.
+3. Run linters, if there are issues, fix them.
 4. Go to the step 1 if you changed something in the process.
 5. Finish.
 
-We may need coding agents on the each step of the process, but there no reason for agents to manage the whole loop by themselves — it takes longer time, spends tokens and confuses agents.
+We may need coding agents on the each step of the process, but there no reason for agents to manage the whole loop by themselves — it takes longer time, spends tokens and confuses agents because they need to reason over long contexts.
 
-## Primary Rules
+## Primary rules for agents
 
+- Donna stores all project-related data in `.donna` directory in the project root.
 - All work is always done in the context of a session. There is only one active session at a time.
 - You MUST always work on one task assigned to you.
-- If developer asked you to do something and you have no session, you create one with the `donna` tool.
-- If you have a session, you MUST keep all the information about it in your memory. Ask `donna` tool for the session details when you forget something.
+- You MUST keep all the information about the session in your memory.
+- You always can ask the `donna` tool for the session details if you forget something.
 
-## Protocol
+## CLI
+
+### Protocol
 
 Protocol selects the output formatting and behavior of Donna's CLI for different consumers (humans, LLMs, automation).
-When an agent invokes Donna, it SHOULD use the `llm` protocol (`-p llm`) unless the workflow explicitly requires another protocol.
-
-### Session workflow
-
-- You start session by calling `donna -p <protocol> sessions start`.
-- After you started a session:
-  1. List all possible workflows with command `donna -p <protocol> artifacts list`.
-  2. Choose the most appropriate workflow for the task you are going to work on or ask the developer if you are not sure which workflow to choose.
-  3. Start working by calling `donna -p <protocol> sessions run <workflow-id>`.
-  4. The `donna` tool will output descriptions of all operations it performs to complete the story.
-  5. The `donna` tool will output **action requests** that you MUST perform. You MUST follow these instructions precisely.
-- When you done doing your part, you call `donna -p <protocol> sessions action-request-completed <action-request-id> <next-full-operation-id>` to report that you completed the action request. `<next-full-operation-id>` MUST contain full identifier of the next operation, like `<world>:<artifact>:<operation-id>`.
-- After you report the result:
-  1. The `donna` tool will output what you need to do next.
-  2. You repeat the process until the story is completed.
+When an agent invokes Donna, it SHOULD use the `llm` protocol (pass an `-p llm` argument) unless the developer explicitly instructs otherwise.
+
+### Protocol cells
+
+Donna communicates its progress and requests by outputting inrofmation organized in "cells". There are two kinds of cells output:
+
+- Log cells — `DONNA LOG: <log-message>` — one line messages describing what Donna is doing. Mostly it is an information about the next operation being executed.
+- Info cells — multiline cells with structured header and freeform body.
+
+An example of an info cell:
+
+```
+--DONNA-CELL eZVkOwNPTHmadXpaHDUBNA BEGIN--
+kind=action_request
+media_type=text/markdown
+action_request_id=AR-65-bd
+
+<here goes the multiline markdown content of the action request>
+
+--DONNA-CELL eZVkOwNPTHmadXpaHDUBNA END--
+```
+
+Donna can omit log cell start and end markers if a command produces only a single cell.
+
+Donna renders cells differently, depending on the protocol used.
+
+### Commands
+
+There are three sets of commands:
+
+- `donna -p <protocol> workspaces …` — manages workspaces. Most-likely it will be used once per your project to initialize it.
+- `donna -p <protocol> sessions …` — manages sessions. You will use these commands to start, push forward, and manage your work.
+- `donna -p <protocol> artifacts …` — manages artifacts. You will use these commands to read and update artifacts you are working with.
+
+Use:
+
+- `donna -p <protocol> <command> --help` to get the list of available subcommands.
+- `donna -p <protocol> <command> <subcommand> --help` to get the help on specific subcommand.
+
+### Workspaces
+
+Run `donna -p <protocol> workspaces init [<directory-path>]` to initialize Donna workspace in the given directory. If `<directory-path>` is omitted, Donna will initialize workspace in the current working directory.
+
+It is a one time operation you need to perform once per project to create a place where Donna will store all its data.
+
+### Starting sessions
+
+The developer is responsible for starting a new session.
+
+You are allowed to start a new session in the next cases:
+
+1. There is no active session.
+2. The developer explicitly instructed you to start a new session.
+
+You start session by calling `donna -p <protocol> sessions start`.
+
+### Session flow
+
+After the session starts you MUST follow the next workflow to perform your work:
+
+1. List all possible workflows with command `donna -p <protocol> artifacts list`.
+2. Choose the most appropriate workflow for the task you are going to work on or ask the developer if you are not sure which workflow to choose.
+3. Start chosen workflow by calling `donna -p <protocol> sessions run <workflow-id>`.
+4. Donna will output descriptions of all operations it performs to complete the work.
+5. Donna will output **action requests** that you MUST perform. You MUST follow these instructions precisely.
+6. When you done processing an action request, call `donna -p <protocol> sessions action-request-completed <action-request-id> <next-full-operation-id>` to report request completion. `<next-full-operation-id>` MUST contain full identifier of the next operation, like `<world>:<artifact>:<operation-id>`.
+7. After you complete an action request, Donna will continue workflow execution and output what you need to do next.
+
+You MUST continue following Donna's instructions until the workflow is completed.
+
+### Session state
+
+- `donna -p <protocol> sessions status` — get the status of the current session.
+- `donna -p <protocol> sessions details` — get detailed information about the current session, including list of active action requests.
+- `donna -p <protocol> sessions start` — start a new session. This command resets session state AND removes all session-level artifacts.
+- Run `donna -p <protocol> sessions reset` to reset the current session. This command resets session state BUT keeps all session-level artifacts. Use this command when you need to restart the worklow but keep all the artifacts you created during the session.
 
 ### Starting work
 
-- If the developer asked you to do something:
-  - run `donna -p <protocol> sessions status` to get the status of the current session.
-  - or run `donna -p <protocol> sessions details` to get detailed information about the current session, including list of active action requests.
-  - If there is no active session, start a new session by calling `donna -p <protocol> sessions start`.
-  - If the session is already active and there are no unfinished work in it, start a new session by calling `donna -p <protocol> sessions start`.
-  - If the session is already active and there are unfinished work in it, you MUST ask the developer whether to continue the work in the current session or start a new one.
-- If the developer asked you to continue your work, you MUST call `donna -p <protocol> sessions continue` to get your instructions on what to do next.
+If the developer asked you to do something new:
+
+- Run `donna -p <protocol> sessions status` to get the status of the current session.
+- If there is no active session, start a new session by calling `donna -p <protocol> sessions start`.
+- If the session is active and there are unfinished work in it, you MUST ask the developer whether to continue the work in the current session or start a new one.
+- If the session is active and there are no unfinished work in it, follow the instructions in the `Session flow` section to choose and start a new workflow.
+
+### Continuing work
+
+If the developer asked you to continue your work, you MUST call `donna -p <protocol> sessions continue` to get your instructions on what to do next.
+
+If Donna tells you there is no work left, you MUST inform the developer that there is no work left in the current session.
 
 ### Working with artifacts
 
 An artifact is a markdown document with extra metadata stored in one of the Donna's worlds.
 
-Use the next commands to work with artifacts
+Use the next commands to work with artifacts:
 
-- `donna -p <protocol> artifacts list [--pattern <artifact-pattern>]` — list all artifacts corresponding to the given pattern. If `<artifact-pattern>` is omitted, list all artifacts in all worlds. Use this command when you need to find an artifact or see what artifacts are available.
-- `donna -p <protocol> artifacts view <world>:<artifact>` — get the meaningful (rendered) content of the artifact. This command shows the rendered information about the artifact. Use this command when you need to read the artifact content.
-- `donna -p <protocol> artifacts fetch <world>:<artifact>` — download the original source of the artifact content, outputs the file path to the artifact's copy you can change. Use this command when you need to change the content of the artifact.
+- `donna -p <protocol> artifacts list [<artifact-pattern>]` — list all artifacts corresponding to the given pattern. If `<artifact-pattern>` is omitted, list all artifacts in all worlds. Use this command when you need to find an artifact or see what artifacts are available.
+- `donna -p <protocol> artifacts view <artifact-pattern>` — get the meaningful (rendered) content of all matching artifacts. This command shows the rendered information about each artifact. Use this command when you need to read artifact content.
+- `donna -p <protocol> artifacts fetch <world>:<artifact>` — download the original source of the artifact content, outputs the file path to the artifact's copy, you can change. Use this command when you need to change the content of the artifact.
+- `donna -p <protocol> artifacts tmp <slug>.<extension>` — create a temporary file for artifact-related work and output its path.
 - `donna -p <protocol> artifacts update <world>:<artifact> <file-path>` — upload the given file as the artifact. Use this command when you finished changing the content of the artifact.
+- `donna -p <protocol> artifacts copy <artifact-id-from> <artifact-id-to>` — copy an artifact source to another artifact ID (can be in a different world). This overwrites the destination if it exists.
+- `donna -p <protocol> artifacts move <artifact-id-from> <artifact-id-to>` — copy an artifact source to another artifact ID and remove the original. This overwrites the destination if it exists.
+- `donna -p <protocol> artifacts remove <artifact-pattern>` — remove artifacts matching a pattern. Use this command when you need to delete artifacts.
 - `donna -p <protocol> artifacts validate <world>:<artifact>` — validate the given artifact to ensure it is correct and has no issues.
-- `donna -p <protocol> artifacts validate-all [--pattern <artifact-pattern>]` — validate all artifacts corresponding to the given pattern.
+- `donna -p <protocol> artifacts validate-all [<artifact-pattern>]` — validate all artifacts corresponding to the given pattern. If `<artifact-pattern>` is omitted, validate all artifacts in all worlds.
+
+Commands that accept an artifact pattern (`artifacts list`, `artifacts view`, `artifacts remove`, `artifacts validate-all`) also accept a repeatable `--tag <tag>` option to filter by artifact tags. When multiple tags are provided, only artifacts that include **all** specified tags are matched.
 
 The format of `<artifact-pattern>` is as follows:
 
@@ -95,7 +170,7 @@ The format of `<artifact-pattern>` is as follows:
   3. Specifications in `project:` world.
   4. This document.
 
-**All Donna CLI commands MUST include an explicit protocol selection using `-p <mode>`.** Like `donna -p llm <command>`.
+**All Donna CLI commands MUST include an explicit protocol selection using `-p <protocol>`.** Like `donna -p llm <command>`.
 
 **Pass text arguments to the tool in quotes with respect to escaping.** The tool MUST receive the exact text you want to pass as an argument.