DYN-10982: Add area READMEs and cap the agent instruction files - #17386

Purpose

DYN-10982 follow-up to #17379. The 2026-10-07 Agent-Friendly Codebase audit of master noted two documentation gaps that #17379 didn't cover:

• src/DynamoCore, src/Engine and src/Libraries have no local orientation. The area map exists only in the on-demand dynamo-onboarding skill.
• .github/copilot-instructions.md, which Copilot always loads, was 244 lines, just under the 250-line limit the audit applies.

This PR adds area READMEs and gives the Copilot file headroom that a gate now protects. No production code changes.

Key changes:

• Area READMEs: new README.md in src/DynamoCore/, src/Engine/ and src/Libraries/ (26–28 lines each). Each covers what the area is and isn't, its main projects, the files to open first, where its tests live, and which contracts apply. Each links to the matching AGENTS.md sections (Running a Single Test, Blast Radius, Node Registration Patterns, Proof Checklist) instead of copying them.
  • Dependency statements were checked against the .csproj ProjectReferences; nothing in src/Engine references DynamoCore.
  • Package membership was checked against the nuspecs.
  • AGENTS.md § Architecture and the Copilot Project Structure section point to the READMEs.
• Copilot file 244 → 197 lines:
  • The node-registration code samples, the debugging detail and the Blast Radius detail are now short summaries with a link to the matching AGENTS.md section.
  • Small subsections are folded together.
  • Every dotnet/msbuild line, the PublicAPI project list, and the security, PublicAPI, localization and CPM rules are unchanged.
• Line budget in check_instruction_drift.ps1: the gate now also fails if AGENTS.md or copilot-instructions.md goes over 250 lines (one $maxInstructionLines variable), counted like wc -l. It reports both counts and their headroom in -Report and the step summary.
• Small fixes:
  • The UI test folders are DynamoCoreWpf2Tests/DynamoCoreWpf3Tests, not DynamoCoreWpfTests2/3; fixed in both instruction files.
  • The Copilot skills list was missing dynamo-release-notes.
  • The Copilot file's Contributing Guide link pointed to the non-existent .github/CONTRIBUTING.md.
  • The Copilot file was missing its final newline.

Declarations

Check these if you believe they are true

• Is documented according to the standards
• The level of testing this PR includes is appropriate
• Changes to the API follow Semantic Versioning and are documented in the API Changes document.

Release Notes

N/A

Reviewers

@DynamoDS/eidos

Notes to reviewers:

• The PowerShell change hasn't been run locally, because the authoring machine has no pwsh. Both checks (command/PublicAPI parity and the new line budget) were re-implemented in Python and run on the edited files:

  • 0 drift: the same 12 dotnet/msbuild lines and the same four PublicAPI projects in both files;
  • AGENTS.md 199/250 and the Copilot file 197/250;
  • padding the Copilot file to 251 lines fails as expected.

  CI's "Validate AGENTS.md / copilot-instructions.md Parity" job runs the real script on this PR.

• Every relative link and anchor in the changed files resolves, and every path named in the READMEs exists.

• The unit-tests-in-CI gap is still left to DYN-10984: Run engine tests (ProtoTest) in GitHub Actions #17370.

FYIs

🤖 Generated with Claude Code