Two rulesDirect user instructions outrank workspace prose. Inside the workspace chain, the more specific directory wins.

Choose by lifetime, not convenience.

Every DSH SessionUser-global$DSH_HOME/AGENTS.md

One fixed file, no global local-overlay.

One repositoryProject baserepo/AGENTS.md

Versioned policy from project root to cwd.

One developerLocal overlayAGENTS.local.md

Loads after base candidates in that directory.

One subtreeNested scopesrc/AGENTS.md

Discovered after structured fs work reaches it.

One task typeSkillSKILL.md

Loaded when the task matches or the user invokes it.

Baseline first. Nested context later.

Session startsglobalroot baseroot localcwd chain
Structured fs succeedsnew nestedchangedremoved
Next Agent stepone durable update

Shell navigation is not discovery.

bash: cd src

No persistent shell state and no reliable structured filesystem boundary.

Does not load nested instructions
read: src/index.ts

A successful first-party fs result reaches the descendant scope.

Queues nested instructions

One path currently has two meanings.

User-global meaning$DSH_HOME/AGENTS.md

Applies to every Session.

Wanted project meaning$DSH_HOME/AGENTS.md

Applies only while editing DSH configuration.

rc.7 provides no second official global path, so these policies cannot be separated in the same file. Treat it as global. Use direct task instructions, an explicit Skill, or a separate configuration repository for local guidance.

Budget preserves specificity.

Dropped firstbroader global prose
Preservedproject instructions
Preserved longestmost-specific file

Prove the active chain.

Primary evidence.

Keep the complete scope runbook.

The canonical guide covers authority, baseline order, local overlays, nested refresh, budgets, collisions, diagnosis, and acceptance.

Read and star on GitHub