feat: add $DOCS_DIR variable for configurable documentation path (coleam00#982)

Projects with docs outside `docs/` (e.g., `packages/docs-web/src/content/docs/`)
get broken bundled commands because the path is hardcoded. Add `docs.path` to
`.archon/config.yaml` and thread it through the workflow engine as `$DOCS_DIR`
(default: `docs/`), following the same pipeline as `$BASE_BRANCH`.

Changes:
- Add `docs.path` to RepoConfig and `docsPath` to MergedConfig/WorkflowConfig
- Thread `docsDir` through executor-shared, executor, and dag-executor
- Update bundled commands to use `$DOCS_DIR` instead of hardcoded `docs/`
- Add optional docs path prompt to `archon setup`
- Add variable reference and configuration documentation
- Resolve pre-existing merge conflicts in server/api.ts

Fixes coleam00#982

Author: Wirasm

.archon/commands/defaults/archon-docs-impact-agent.md

@@ -44,7 +44,7 @@ gh pr diff {number}
 cat CLAUDE.md
 
 # List docs folder
-ls -la docs/
+ls -la $DOCS_DIR
 
 # List agent definitions
 ls -la .claude/agents/ 2>/dev/null || true
@@ -131,8 +131,8 @@ Write to `$ARTIFACTS_DIR/review/docs-impact-findings.md`:
 | Document | Impact | Required Update |
 |----------|--------|-----------------|
 | CLAUDE.md | NONE/LOW/HIGH | {description or "None"} |
-| docs/architecture.md | NONE/LOW/HIGH | {description or "None"} |
-| docs/configuration.md | NONE/LOW/HIGH | {description or "None"} |
+| $DOCS_DIR/architecture.md | NONE/LOW/HIGH | {description or "None"} |
+| $DOCS_DIR/configuration.md | NONE/LOW/HIGH | {description or "None"} |
 | README.md | NONE/LOW/HIGH | {description or "None"} |
 | .claude/agents/*.md | NONE/LOW/HIGH | {description or "None"} |
 | .archon/commands/*.md | NONE/LOW/HIGH | {description or "None"} |

.archon/commands/defaults/archon-pr-review-scope.md

@@ -351,7 +351,7 @@ Write `$ARTIFACTS_DIR/review/scope.md`:
 - `src/...test.ts`
 
 ### Documentation ({count})
-- `docs/...`
+- `$DOCS_DIR/...`
 - `README.md`
 
 ### Configuration ({count})
@@ -367,7 +367,7 @@ Based on changes, reviewers should focus on:
 2. **Error Handling**: {files with try/catch, error handling}
 3. **Test Coverage**: {new functionality needing tests}
 4. **Comments/Docs**: {files with documentation changes}
-5. **Docs Impact**: {check if CLAUDE.md or docs/ need updates}
+5. **Docs Impact**: {check if CLAUDE.md or $DOCS_DIR need updates}
 
 ---
 

.archon/commands/defaults/archon-workflow-summary.md

@@ -206,7 +206,7 @@ Structure the output for easy decision-making:
 | File | Section | Update Needed |
 |------|---------|---------------|
 | CLAUDE.md | Database Schema | Add ended_reason column |
-| docs/architecture.md | Sessions | Update deactivateSession signature |
+| $DOCS_DIR/architecture.md | Sessions | Update deactivateSession signature |
 
 **Your choice**:
 - [ ] Send docs agent to fix all

packages/cli/src/commands/setup.ts

@@ -1535,6 +1535,29 @@ export async function setupCommand(options: SetupOptions): Promise<void> {
     skillInstalledPath = join(skillTarget, '.claude', 'skills', 'archon');
   }
 
+  // Optional: configure docs directory
+  const wantsDocsPath = await confirm({
+    message: 'Configure a non-default docs directory? (default: docs/)',
+    initialValue: false,
+  });
+
+  if (!isCancel(wantsDocsPath) && wantsDocsPath) {
+    const docsPath = await text({
+      message: 'Where are your project docs? (relative to repo root)',
+      placeholder: 'docs/',
+    });
+
+    if (!isCancel(docsPath) && typeof docsPath === 'string' && docsPath.trim()) {
+      const archonDir = join(options.repoPath, '.archon');
+      mkdirSync(archonDir, { recursive: true });
+      const configPath = join(archonDir, 'config.yaml');
+      const existing = existsSync(configPath) ? readFileSync(configPath, 'utf-8') : '';
+      if (!existing.includes('docs:')) {
+        writeFileSync(configPath, existing + `\ndocs:\n  path: ${docsPath.trim()}\n`);
+      }
+    }
+  }
+
   // Summary
   const configuredPlatforms: string[] = [];
   if (config.platforms.github) configuredPlatforms.push('GitHub');

packages/core/src/config/config-loader.ts

@@ -368,6 +368,11 @@ function mergeRepoConfig(merged: MergedConfig, repo: RepoConfig): MergedConfig {
     result.baseBranch = repo.worktree.baseBranch.trim();
   }
 
+  // Propagate docs path for $DOCS_DIR substitution in workflow commands
+  if (repo.docs?.path?.trim()) {
+    result.docsPath = repo.docs.path.trim();
+  }
+
   // Propagate per-project env vars from repo config
   if (repo.env) {
     result.envVars = { ...result.envVars, ...repo.env };

packages/core/src/config/config-types.ts

@@ -141,6 +141,17 @@ export interface RepoConfig {
     copyFiles?: string[];
   };
 
+  /**
+   * Documentation directory settings
+   */
+  docs?: {
+    /**
+     * Path to documentation directory (relative to repo root)
+     * @default 'docs/'
+     */
+    path?: string;
+  };
+
   /**
    * Per-project environment variables injected into Claude SDK subprocess env.
    * Values here override process.env for workflow node execution.
@@ -219,6 +230,12 @@ export interface MergedConfig {
    * When undefined, workflows referencing $BASE_BRANCH will fail with an error.
    */
   baseBranch?: string;
+  /**
+   * Docs directory path from repo config (docs.path).
+   * Used for $DOCS_DIR substitution in workflow commands.
+   * @default 'docs/'
+   */
+  docsPath?: string;
   /**
    * Merged per-project env vars from .archon/config.yaml env: section.
    * DB env vars (from Web UI) are merged on top by executeWorkflow.

packages/docs-web/src/content/docs/getting-started/configuration.md

@@ -35,6 +35,9 @@ assistants:
   codex:
     model: gpt-5.3-codex
     modelReasoningEffort: medium
+
+# docs:
+#   path: packages/docs-web/src/content/docs  # Optional: default is docs/
 ```
 
 See the [full configuration reference](/reference/configuration/) for all options.

packages/docs-web/src/content/docs/reference/configuration.md

@@ -114,6 +114,10 @@ worktree:
     - .env.example -> .env  # Rename during copy
     - .vscode               # Copy entire directory
 
+# Documentation directory
+docs:
+  path: docs  # Optional: default is docs/
+
 # Defaults configuration
 defaults:
   loadDefaultCommands: true   # Load app's bundled default commands at runtime
@@ -157,6 +161,8 @@ This is useful when you maintain coding style or identity preferences in `~/.cla
 2. If omitted: Auto-detects the default branch via `git remote show origin`. Works without any config for standard repos.
 3. If auto-detection fails and a workflow references `$BASE_BRANCH`: Fails with an error explaining the resolution chain.
 
+**Docs path behavior:** The `docs.path` setting controls where the `$DOCS_DIR` variable points. When not configured, `$DOCS_DIR` defaults to `docs/`. Unlike `$BASE_BRANCH`, this variable always has a safe default and never throws an error. Configure it when your documentation lives outside the standard `docs/` directory (e.g., `packages/docs-web/src/content/docs`).
+
 ## Environment Variables
 
 Environment variables override all other configuration. They are organized by category below.

packages/docs-web/src/content/docs/reference/variables.md

@@ -21,6 +21,7 @@ These variables are substituted by the workflow executor in all node types (`com
 | `$WORKFLOW_ID` | Unique ID for the current workflow run | Useful for artifact naming and log correlation |
 | `$ARTIFACTS_DIR` | Pre-created external artifacts directory (`~/.archon/workspaces/<owner>/<repo>/artifacts/runs/<id>/`) | Always exists before node execution; stored outside the repo to avoid polluting the working tree |
 | `$BASE_BRANCH` | Base branch for git operations | Auto-detected from the repository's default branch, or set via `worktree.baseBranch` in `.archon/config.yaml`. Throws an error if referenced in a prompt but cannot be resolved |
+| `$DOCS_DIR` | Documentation directory path | Configured via `docs.path` in `.archon/config.yaml`. Defaults to `docs/` when not set. Never throws |
 | `$CONTEXT` | GitHub issue or PR context, if available | Populated when the workflow is triggered from a GitHub issue/PR. Replaced with empty string when unavailable |
 | `$EXTERNAL_CONTEXT` | Same as `$CONTEXT` | Alias |
 | `$ISSUE_CONTEXT` | Same as `$CONTEXT` | Alias |
@@ -87,7 +88,7 @@ nodes:
 
 Variables are substituted in a defined order:
 
-1. **Workflow variables** -- `$WORKFLOW_ID`, `$USER_MESSAGE`, `$ARGUMENTS`, `$ARTIFACTS_DIR`, `$BASE_BRANCH`, `$LOOP_USER_INPUT`, `$REJECTION_REASON`
+1. **Workflow variables** -- `$WORKFLOW_ID`, `$USER_MESSAGE`, `$ARGUMENTS`, `$ARTIFACTS_DIR`, `$BASE_BRANCH`, `$DOCS_DIR`, `$LOOP_USER_INPUT`, `$REJECTION_REASON`
 2. **Context variables** -- `$CONTEXT`, `$EXTERNAL_CONTEXT`, `$ISSUE_CONTEXT`
 3. **Node output references** -- `$nodeId.output`, `$nodeId.output.field`
 
@@ -102,6 +103,7 @@ Positional arguments (`$1` through `$9`) are substituted separately by the comma
 | `$WORKFLOW_ID` | Yes | No | No |
 | `$ARTIFACTS_DIR` | Yes | No | No |
 | `$BASE_BRANCH` | Yes | No | No |
+| `$DOCS_DIR` | Yes | No | No |
 | `$CONTEXT` / aliases | Yes | No | No |
 | `$LOOP_USER_INPUT` | Yes (loop nodes) | No | No |
 | `$REJECTION_REASON` | Yes (`on_reject` only) | No | No |

packages/server/src/routes/api.ts

@@ -36,12 +36,9 @@ import {
   getDefaultCommandsPath,
   getDefaultWorkflowsPath,
   getArchonWorkspacesPath,
-<<<<<<< HEAD
   getRunArtifactsPath,
   getArchonHome,
-=======
   isDocker,
->>>>>>> 75eec3f7 (fix: hide 'Open in IDE' button in Docker deployments (#898))
 } from '@archon/paths';
 import { discoverWorkflowsWithConfig } from '@archon/workflows/workflow-discovery';
 import { parseWorkflow } from '@archon/workflows/loader';
@@ -798,11 +795,8 @@ const getHealthRoute = createRoute({
               adapter: z.string(),
               concurrency: z.record(z.unknown()),
               runningWorkflows: z.number(),
-<<<<<<< HEAD
               version: z.string().optional(),
-=======
               is_docker: z.boolean(),
->>>>>>> 75eec3f7 (fix: hide 'Open in IDE' button in Docker deployments (#898))
             })
             .openapi('HealthResponse'),
         },
@@ -2495,11 +2489,8 @@ export function registerApiRoutes(
         activeConversationIds: allActiveIds,
       },
       runningWorkflows: runningWorkflowRows.length,
-<<<<<<< HEAD
       version: appVersion,
-=======
       is_docker: isDocker(),
->>>>>>> 75eec3f7 (fix: hide 'Open in IDE' button in Docker deployments (#898))
     });
   });
 }