docs: document the Documents feature

.vitepress/config.js

@@ -122,6 +122,7 @@ const fullSidebar = [
         collapsed: true,
         items: [
           { text: "Cockpit", link: "/web-ui/cockpit" },
+          { text: "Documents", link: "/web-ui/documents" },
           { text: "Workspaces", link: "/web-ui/workspaces" },
           { text: "Profiles", link: "/web-ui/profiles" },
           { text: "DAG Secret Refs", link: "/web-ui/secrets" },

[page].md

@@ -133,6 +133,10 @@ Want to explore without installing anything? Open the [live demo](https://dagu-d
     <h3><a href="/overview/web-ui">See every run</a></h3>
     <p>Use the Web UI to inspect live status, read step logs, review history, retry failures, and edit workflow YAML.</p>
   </div>
+  <div class="overview-card">
+    <h3><a href="/web-ui/documents">Keep runbooks with workflows</a></h3>
+    <p>Write Markdown, preview Mermaid diagrams, organize nested documents, search their contents, and synchronize them through Git.</p>
+  </div>
   <div class="overview-card">
     <h3><a href="/writing-workflows/error-handling">Make jobs reliable</a></h3>
     <p>Add dependencies, schedules, retries, timeouts, approvals, notifications, and artifacts in the workflow file.</p>
@@ -164,6 +168,10 @@ Want to explore without installing anything? Open the [live demo](https://dagu-d
     <h3><a href="/writing-workflows/examples">Workflow examples</a></h3>
     <p>Start from practical YAML for scripts, data jobs, containers, and operations.</p>
   </div>
+  <div class="step-card">
+    <h3><a href="/web-ui/documents">Documents and runbooks</a></h3>
+    <p>Keep operational Markdown, diagrams, and troubleshooting guides next to the workflows they explain.</p>
+  </div>
   <div class="step-card">
     <h3><a href="/getting-started/concepts">Core concepts</a></h3>
     <p>Learn how steps, dependencies, parameters, runs, and schedules fit together.</p>

getting-started/cli.md

@@ -866,6 +866,7 @@ Provide either an item ID or `--all`, not both.
 
 ```bash
 dagu sync publish my-dag -m "Update dag"
+dagu sync publish docs/operations/runbook -m "Update runbook"
 dagu sync publish skills/review -m "Update review skill"
 dagu sync publish --all -m "Batch update"
 dagu sync publish my-dag --force -m "Overwrite remote"
@@ -944,6 +945,7 @@ Provide either an item ID or `--all-missing`, not both. Untracked items cannot b
 
 ```bash
 dagu sync delete my-dag -m "Remove old dag"
+dagu sync delete docs/operations/runbook -m "Remove old runbook"
 dagu sync delete my-dag --force -m "Remove despite modifications"
 dagu sync delete --all-missing -m "Clean up missing"
 dagu sync delete my-dag --dry-run
@@ -968,6 +970,7 @@ Both source and destination must be of the same kind.
 
 ```bash
 dagu sync mv old-dag new-dag -m "Rename workflow"
+dagu sync mv docs/operations/runbook docs/operations/deploy -m "Rename runbook"
 dagu sync mv old-dag new-dag --force -m "Move despite conflict"
 dagu sync mv old-dag new-dag --dry-run
 ```

overview/web-ui.md

@@ -1,6 +1,6 @@
 # Web UI
 
-Use Dagu's web UI to run workflows, inspect results, edit DAGs, review logs, and manage the server from a browser.
+Use Dagu's web UI to run workflows, inspect results, edit DAGs, maintain Markdown documents, review logs, and manage the server from a browser.
 
 ## Start the UI
 
@@ -21,18 +21,19 @@ dagu start-all --host 0.0.0.0 --port 9000
 Dagu's UI is organized around a few everyday jobs:
 
 - **Cockpit** for a live board of recent runs
+- **Documents** for Markdown runbooks, Mermaid diagrams, and operational notes
 - **Dashboard** for recent activity and trends
 - **Definitions** for the list of workflows
 - **Run details** for human tasks, approvals, outputs, artifacts, logs, and retries
 - **Notifications** for Slack, email, Telegram, and webhook routing
 - **Incidents** for PagerDuty and SolarWinds Incident Response routing
 - **Profiles** for runtime variables and secrets selected when a run starts
-- **Search** for finding workflows quickly
+- **Search** for finding workflows and document content quickly
 - **System Status** for scheduler, coordinator, worker, and resource health
 
 ## Workspace Selector
 
-The workspace selector sits at the top of the navigation and affects workspace-aware pages such as Cockpit, Dashboard, Definitions, Runs, Search, and Design.
+The workspace selector sits at the top of the navigation and affects workspace-aware pages such as Cockpit, Documents, Dashboard, Definitions, Runs, Search, and Design.
 
 ![Workspace selector](/web-ui-workspace-selector-demo.png)
 
@@ -59,6 +60,24 @@ Use it when you want to:
 
 See [Cockpit](/web-ui/cockpit) for the dedicated guide.
 
+## Documents
+
+Documents gives runbooks and workflow notes a first-class home in Dagu.
+
+![Documents editor](/documents.png)
+
+Use it to:
+
+- organize Markdown files in a nested tree
+- work across several documents with tabs
+- edit and preview Markdown, including Mermaid diagrams
+- navigate long documents from their heading outline
+- search file names and contents
+- keep documents scoped to a workspace
+- publish and pull documents with Git Sync
+
+Unsaved drafts are kept in browser storage, and the editor reports external changes before they can overwrite local work. See [Documents](/web-ui/documents) for file operations, workspace behavior, storage configuration, runtime paths, and Git Sync.
+
 ## Dashboard
 
 The Dashboard gives you a broader operations view than Cockpit.
@@ -197,6 +216,7 @@ Search helps when you know roughly what you need but not exactly where it lives.
 You can search:
 
 - **DAGs** for workflow definitions
+- **Documents** for Markdown files and matching lines
 
 ## Profiles & Secrets
 
@@ -310,6 +330,7 @@ ui:
 
 - [Workspaces](/web-ui/workspaces)
 - [Cockpit](/web-ui/cockpit)
+- [Documents](/web-ui/documents)
 - [Profiles and profile-owned secrets](/web-ui/profiles)
 - [Notifications](/web-ui/notifications)
 - [Incident Routing](/web-ui/incidents)

public/_redirects

@@ -54,8 +54,8 @@
 /features/data-flow/ /writing-workflows/data-flow 301
 /features/distributed-execution /server-admin/distributed/ 301
 /features/distributed-execution/ /server-admin/distributed/ 301
-/features/documents /overview/web-ui 301
-/features/documents/ /overview/web-ui 301
+/features/documents /web-ui/documents 301
+/features/documents/ /web-ui/documents 301
 /features/email-notifications /writing-workflows/email-notifications 301
 /features/email-notifications/ /writing-workflows/email-notifications 301
 /features/exec /migration/from-cron 301
@@ -128,8 +128,6 @@
 /step-types/harness /step-types/harness/ 301
 /server-admin/mcp /mcp/ 301
 /server-admin/mcp/ /mcp/ 301
-/web-ui/documents /overview/web-ui 301
-/web-ui/documents/ /overview/web-ui 301
 
 # Earlier guide hierarchy
 /github-integration /dagu-actions/official/github-cli 301

server-admin/configuration.md

@@ -56,6 +56,7 @@ auth:
 
 paths:
   dags_dir: /opt/dagu/dags
+  docs_dir: /opt/dagu/dags/docs
   log_dir: /var/log/dagu
   data_dir: /var/lib/dagu/data
   dag_state_dir: /var/lib/dagu/data/dag-state
@@ -69,6 +70,7 @@ Configuration fields can be overridden with `DAGU_` environment variables. Neste
 export DAGU_HOST=0.0.0.0
 export DAGU_PORT=8080
 export DAGU_DAGS_DIR=/opt/dagu/dags
+export DAGU_DOCS_DIR=/opt/dagu/dags/docs
 export DAGU_DAG_DISCOVERY_RECURSIVE=true
 export DAGU_DATA_DIR=/var/lib/dagu/data
 export DAGU_DAG_STATE_DIR=/var/lib/dagu/data/dag-state
@@ -84,6 +86,7 @@ Common examples:
 | `DAGU_PORT` | `port` | Web UI port |
 | `DAGU_PUBLIC_URL` | `public_url` | External URL used in generated links |
 | `DAGU_DAGS_DIR` | `paths.dags_dir` | DAG definition directory |
+| `DAGU_DOCS_DIR` | `paths.docs_dir` | Markdown document directory |
 | `DAGU_DAG_DISCOVERY_RECURSIVE` | `dag_discovery.recursive` | Discover DAG definitions in subdirectories |
 | `DAGU_DATA_DIR` | `paths.data_dir` | Data directory used by derived stores |
 | `DAGU_LOG_DIR` | `paths.log_dir` | Log directory |
@@ -127,6 +130,7 @@ Typical layout:
 |-- config.yaml
 |-- base.yaml
 |-- dags/
+|   `-- docs/
 |-- logs/
 `-- data/
     |-- artifacts/
@@ -145,6 +149,7 @@ Most persistent runtime data is stored under `paths.data_dir` by default.
 | Config field | Default | Purpose |
 | --- | --- | --- |
 | `paths.dags_dir` | `~/.config/dagu/dags` | DAG definitions |
+| `paths.docs_dir` | `{dags_dir}/docs` | Markdown documents and runbooks |
 | `paths.log_dir` | `~/.local/share/dagu/logs` | DAG logs |
 | `paths.data_dir` | `~/.local/share/dagu/data` | Base directory for runtime data |
 | `paths.tools_dir` | `{data_dir}/tools` | Managed DAG tool cache |
@@ -158,6 +163,35 @@ Most persistent runtime data is stored under `paths.data_dir` by default.
 | `paths.contexts_dir` | `{data_dir}/contexts` | CLI contexts |
 | `paths.workspaces_dir` | `{data_dir}/workspaces` | Web UI workspaces |
 
+## Documents Directory
+
+`paths.docs_dir` is the storage root for Markdown files managed by the Documents Web UI and Git Sync:
+
+```yaml
+paths:
+  dags_dir: /opt/dagu/dags
+  docs_dir: /srv/dagu/documents
+```
+
+The equivalent environment variable is:
+
+```bash
+export DAGU_DOCS_DIR=/srv/dagu/documents
+```
+
+When `paths.docs_dir` is not configured, Dagu uses `<paths.dags_dir>/docs`. Default-workspace documents live directly in that directory. Named workspaces use a directory named after the workspace:
+
+```text
+/srv/dagu/documents/
+|-- shared-runbook.md
+`-- finance/
+    `-- month-end-close.md
+```
+
+`shared-runbook.md` belongs to Default. The second path is owned by the `finance` workspace when that workspace exists. Treat the document root and workspace records as related state when designing backups. Dagu moves the matching document directory when a workspace is renamed and blocks workspace deletion until its documents are removed.
+
+Each workflow run also receives a per-DAG document path as `${context.paths.docs_dir}` and `DAG_DOCS_DIR`. See [Documents](/web-ui/documents) and [Runtime Context and Variables](/writing-workflows/runtime-variables#documents-directory-context-paths-docs-dir).
+
 ## Recursive DAG Discovery
 
 By default, Dagu discovers DAG definitions only at the top level of
@@ -240,3 +274,4 @@ Do not put `paths`, `auth`, `coordinator`, `worker`, or other server process set
 - [Queue Configuration](/server-admin/queues)
 - [Distributed Execution](/server-admin/distributed/)
 - [Persistent State](/writing-workflows/persistent-state)
+- [Documents](/web-ui/documents)

server-admin/deployment/multi-environment.md

@@ -1,6 +1,6 @@
 # Multi-Environment Deployments
 
-Run a separate Dagu deployment for each environment when development, staging, and production must have independent execution boundaries. Each deployment can synchronize reviewed workflow definitions from Git while keeping its scheduler, workers, storage, credentials, and runtime configuration separate.
+Run a separate Dagu deployment for each environment when development, staging, and production must have independent execution boundaries. Each deployment can synchronize reviewed workflows and documents from Git while keeping its scheduler, workers, storage, credentials, and runtime configuration separate.
 
 ::: warning Do Not Use Workspaces as Environments
 [Workspaces](/web-ui/workspaces) organize and authorize workflows inside one Dagu installation. They do not create separate schedulers, local execution environments, coordinators, workers, queues, storage, or Git Sync configurations.
@@ -32,17 +32,17 @@ Do not mount the same writable data directory into independent environments. Sha
 
 ## Promote Workflows with Git Sync
 
-[Git Sync](/server-admin/git-sync) distributes DAG definitions from a repository. Use a branch promotion workflow so each deployment advances only after the workflow version has passed the preceding environment.
+[Git Sync](/server-admin/git-sync) distributes DAG definitions, Markdown documents, and workflow-authoring skills from a repository. Use a branch promotion workflow so each deployment advances only after the repository version has passed the preceding environment.
 
 A typical flow is:
 
-1. Author and validate a workflow in development.
+1. Author and validate a workflow or its operational documents in development.
 2. Review the change in Git.
 3. Promote the reviewed commit to the branch tracked by staging.
 4. Validate the workflow and its integrations in staging.
 5. Promote the approved commit to the branch tracked by production.
 
-Configure each deployed environment to track its own branch. Staging and production should normally be read-only so workflow edits cannot publish directly from those installations.
+Configure each deployed environment to track its own branch. Staging and production should normally be read-only so workflow and document edits cannot publish directly from those installations.
 
 ```yaml
 # Staging config.yaml

server-admin/git-sync.md

@@ -1,14 +1,17 @@
 # Git Sync
 
-Git Sync keeps Dagu workflows and workflow-authoring skill files aligned with a Git repository.
+Git Sync keeps Dagu workflows, Markdown documents, and workflow-authoring skill files aligned with a Git repository.
 
 ## What It Syncs
 
 Git Sync can track:
 
 - DAG files
+- Markdown documents
 - skills
 
+DAG files live at the configured repository root, documents live under `docs/`, and skills live under `skills/`. Pulling a repository routes each kind to its configured local storage directory.
+
 ## Tracked Items And IDs
 
 Git Sync refers to each tracked file by an `itemId`. You will see that term in the CLI and REST API.
@@ -17,6 +20,7 @@ Git Sync refers to each tracked file by an `itemId`. You will see that term in t
 |---|---|---|
 | `my-dag.yaml` | `my-dag` | `dag` |
 | `subdir/report.yml` | `subdir/report` | `dag` |
+| `docs/operations/runbook.md` | `docs/operations/runbook` | `doc` |
 | `skills/review/SKILL.md` | `skills/review/SKILL` | `skill` |
 
 ## Basic Configuration
@@ -115,6 +119,7 @@ dagu sync pull
 
 ```bash
 dagu sync publish my-dag -m "Update workflow"
+dagu sync publish docs/operations/runbook -m "Update operations runbook"
 dagu sync publish skills/review -m "Update review skill"
 dagu sync publish --all -m "Batch update"
 ```
@@ -137,6 +142,7 @@ dagu sync cleanup
 ```bash
 dagu sync delete my-dag -m "Remove old workflow"
 dagu sync mv old-dag new-dag -m "Rename workflow"
+dagu sync mv docs/operations/runbook docs/operations/deploy -m "Rename runbook"
 ```
 
 ## REST API
@@ -173,11 +179,13 @@ Write operations are blocked when Git Sync is configured as read-only (`push_ena
 ## Operational Notes
 
 - Manage Git Sync through the UI, CLI, or API rather than editing its internal state directly.
+- Documents edited in the Web UI appear as `doc` items in Git Sync status, diff, publish, discard, delete, and move operations.
 - Pull before publishing when multiple people or systems may change the same repository.
 - Use clear commit messages because Git Sync publishes normal Git commits.
 - For staging and production, prefer read-only Git Sync configurations and promote reviewed workflow versions between environment branches. See [Multi-Environment Deployments](/server-admin/deployment/multi-environment).
 
 ## Related Pages
 
 - [Server Administration](/server-admin/)
+- [Documents](/web-ui/documents)
 - [Multi-Environment Deployments](/server-admin/deployment/multi-environment)

server-admin/index.md

@@ -42,6 +42,7 @@ auth:
 
 paths:
   dags_dir: /opt/dagu/workflows
+  docs_dir: /opt/dagu/workflows/docs
   log_dir: /var/log/dagu
 ```
 
@@ -60,6 +61,7 @@ docker run -d \
 **[Configuration](/server-admin/configuration)**
 - Config file, environment variables, and precedence
 - `DAGU_HOME` and path defaults
+- Documents and runbook storage
 - Persistent state directory configuration
 
 **[Server Configuration](/server-admin/server)**
@@ -150,6 +152,7 @@ export DAGU_PORT=8080
 
 # Paths
 export DAGU_DAGS_DIR=/opt/workflows
+export DAGU_DOCS_DIR=/opt/workflows/docs
 export DAGU_LOG_DIR=/var/log/dagu
 
 # Auth
@@ -164,6 +167,7 @@ dagu start-all
 - [Set up authentication](/server-admin/server#authentication) for production
 - [Understand configuration precedence](/server-admin/configuration) before mixing flags, environment variables, and `config.yaml`
 - [Configure base defaults](/server-admin/base-config) for shared DAG settings
+- [Configure Documents](/web-ui/documents) for Markdown runbooks and Git Sync
 - [Configure monitoring](/server-admin/operations#monitoring) for visibility
 - [Set up distributed execution](/server-admin/distributed/) for scaling
 - [Review all options](/server-admin/reference) for fine-tuning

server-admin/reference.md

@@ -56,6 +56,7 @@ sse:
 # Directories (must be under "paths" key)
 paths:
   dags_dir: "~/.config/dagu/dags"
+  docs_dir: ""                # Auto: {dags_dir}/docs
   alt_dags_dir: ""          # Additional read-only DAG directories
   log_dir: "~/.local/share/dagu/logs"
   data_dir: "~/.local/share/dagu/data"
@@ -320,6 +321,7 @@ All options support `DAGU_` prefix.
 - `DAGU_HOME` - Set all directories to this path (can be overridden by `--dagu-home` flag)
 - `DAGU_DAGS_DIR` - DAG definitions
 - `DAGU_DAGS` - Alternative to `DAGU_DAGS_DIR`
+- `DAGU_DOCS_DIR` - Markdown documents and runbooks (default: `{dags_dir}/docs`)
 - `DAGU_ALT_DAGS_DIR` - Additional read-only DAG directories
 - `DAGU_LOG_DIR` - Log files
 - `DAGU_DATA_DIR` - Application data
@@ -771,6 +773,7 @@ peer:
 
 ### Auto-generated Paths
 When not specified, these paths are automatically derived:
+- `paths.docs_dir`: `{paths.dags_dir}/docs` - Stores Markdown documents and runbooks
 - `paths.artifact_dir`: `{paths.data_dir}/artifacts` - Stores DAG run artifacts
 - `paths.tools_dir`: `{paths.data_dir}/tools` - Stores managed DAG tool cache, locks, manifests, and shims
 - `paths.dag_state_dir`: `{paths.data_dir}/dag-state` - Stores persistent DAG state values