Techcle Wiki

PATH FIXES SUMMARY

2 min read

Path Fixes Summary

Date: 2026-02-12
Issue: All absolute paths (/workspace/, /home/coder/src/) replaced with relative paths or environment variables

Changes Made

1. Documentation Cross-References

Files: builder-pattern.md

  • Changed: /workspace/.ai/shared/opencode-session-pattern.md

  • To: ../opencode-session-pattern.md (relative path)

  • Changed: /workspace/.ai/projects/ai-dev/opencode-slack-integration/workspace-pattern-v2.md

  • To: ../opencode-slack-integration/workspace-pattern-v2.md (relative path)

2. Project Path Examples

Files: README.md, acp-protocol.md, api-contract.md, architecture.md, prd.md

  • Changed: /workspace/projects/api-server

  • To: repos/api-server (relative to workspace root)

  • Changed: /workspace/repos/ai-dev

  • To: repos/ai-dev (relative to workspace root)

  • Changed: /workspace/repos/test

  • To: ${WORKSPACE_ROOT}/repos/test (environment variable in curl examples)

3. Builder Workspace Paths

Files: builder-pattern.md, prd.md, opencode-session-pattern.md

  • Changed: /workspace/.builders/<name>
  • To: .builders/<name> (relative to workspace root)

4. Configuration Examples

Files: opencode-session-pattern.md

  • Changed: workspace_root: /workspace

  • To: workspace_root: ${WORKSPACE_ROOT} (environment variable)

  • Changed: builders_dir: /workspace/.builders

  • To: builders_dir: ${WORKSPACE_ROOT}/.builders (environment variable)

  • Changed: builder_path: /workspace/.builders/api-team-abc123

  • To: builder_path: .builders/api-team-abc123 (relative to workspace_root)

5. Conceptual Diagrams

Files: opencode-session-pattern.md

  • Changed: /workspace/ (as volume mount point)
  • To: <workspace-root>/ (generic placeholder)

6. External References

Files: README.md, api-contract.md, architecture.md, prd.md

  • Changed: /workspace/projects/ai-dev/plugins/opencode-bridge/

  • To: projects/ai-dev/plugins/opencode-bridge/ (relative, with note “if it exists”)

  • Changed: /app/skills/coding-agent/SKILL.md

  • To: app/skills/coding-agent/SKILL.md (relative, with note “relative to OpenClaw root”)

  • Changed: /app/gateway/src/tools/

  • To: app/gateway/src/tools/ (relative, with note “relative to OpenClaw root”)

Pattern Applied

For Documentation Cross-References

Use relative paths from the current document location:

[../other-doc.md](../other-doc.md)

For Code/Config Examples

Use relative paths from workspace root or environment variables:

workspace_root: ${WORKSPACE_ROOT}
project: repos/api-server
curl -d '{"project": "${WORKSPACE_ROOT}/repos/test"}'

For Conceptual Diagrams

Use generic placeholders:

<workspace-root>/
├── repos/
├── .builders/
└── .ai/

Verification

All absolute path references have been removed:

  • ✅ No /workspace/ absolute paths in examples
  • ✅ No /home/coder/src/ references
  • ✅ All doc cross-references use relative paths
  • ✅ Config examples use environment variables
  • ✅ Diagrams use generic placeholders

Why This Matters

The workspace root is mounted at different locations depending on the environment:

  • Local dev: /home/coder/src/
  • Docker container: /workspace/
  • K8s pod: /workspace/ (via PVC)
  • CI/CD: /github/workspace/, /app/, etc.

Using relative paths and environment variables ensures documentation and examples work in all environments.

Graph View