Advanced Usage

How Agents Should Read ODS Workspaces

1. Start at the root index.md.
2. Descend through child indexes toward the target document.
3. Read the target frontmatter first.
4. Load depends transitively up to context.max-depth (default 2).
5. Load context.load entries: Document .md paths first, then Resource paths.
6. Skip paths matching context.ignore and workspace ignore:.
7. Prefer stable over draft, and draft over deprecated or archived.

That gives agents a deterministic path instead of a broad scan.

Use the CLI to debug the resolution:

ods context path/to/doc.md

Global Multi-Workspace Tracking (ods workspaces)

ODS background daemons (ods serve) monitor multiple repositories registered in the user’s global machine configuration file (~/.ods/odsconfig.toml):

# Register a workspace for background tracking
ods workspaces add /path/to/my-project

# List all tracked workspaces and pack entries
ods workspaces list

# Remove a workspace from tracking
ods workspaces remove /path/to/my-project

# Print machine config file path (~/.ods/odsconfig.toml)
ods workspaces path

Daemon Execution Modes & Memory Tuning (ods serve)

ods serve supports three execution modes for handling filesystem updates across workspaces:

1. auto (default): Automatically selects watch mode, unless ODS_LOW_MEMORY=1 is set in the environment, in which case it uses poll mode.
2. watch: Real-time OS event watcher (fsnotify/kqueue/inotify) for immediate rename mapping and index regeneration.
3. poll: Periodic polling interval (default 10s). Drops temporary workspace state between ticks for maximum RAM savings in low-memory containerized environments.

# Low-memory polling configuration with RSS memory diagnostics
ODS_LOW_MEMORY=1 ODS_POLL_SECS=30 ods serve --mode poll --memory-report --root .

Large Workspaces

Guidance for tens of thousands of Markdown files:

• Keep profiles small; put custom catalogs in ods-profiles/ or listed profiles: roots.
• Prefer path-derived IDs; pin explicit id: only when renames must not break external refs.
• Run ods index --check and ods lint in CI rather than trusting hand-edited maps.
• Use --level 1 while onboarding noisy trees; enable body-link and graph checks at Level 3 when ready.
• Tooling skips node_modules, target, and similar trees by default and may honor .gitignore.
• Exclude implementation trees with root ignore: (for example src).