The @../AGENTS.md import in component-repo AGENTS.md files silently depends on each repo being checked out as a DocumentServer submodule. In the canonical superproject layout, ../ from sdkjs-forms/ resolves to DocumentServer/ — where AGENTS.md lives. A standalone clone produces no error; the import simply doesn't load.
The same layout invariant applies to the Grunt --addon path resolution: path.join('../../', 'sdkjs-forms') in sdkjs/build/Gruntfile.js expects sdkjs-forms to be a sibling of sdkjs in the workspace — which is only guaranteed in the DocumentServer superproject checkout.
Neither the current AGENTS.md nor the proposed replacement documents this requirement. An agent (or contributor) cloning sdkjs-forms standalone gets silently degraded tooling with no indication why.
What needs doing
Add a brief Checkout section to AGENTS.md (and to web-apps/AGENTS.md when that lands) stating:
- This repo is a DocumentServer submodule — always clone via the superproject (
git submodule update --init --recursive).
- Standalone clones will not resolve
@../AGENTS.md (the shared AI policy and build guide at DocumentServer/AGENTS.md).
- The
grunt --addon=sdkjs-forms path resolution also requires this layout.
Discovered during review of #5.
The
@../AGENTS.mdimport in component-repo AGENTS.md files silently depends on each repo being checked out as a DocumentServer submodule. In the canonical superproject layout,../fromsdkjs-forms/resolves toDocumentServer/— whereAGENTS.mdlives. A standalone clone produces no error; the import simply doesn't load.The same layout invariant applies to the Grunt
--addonpath resolution:path.join('../../', 'sdkjs-forms')insdkjs/build/Gruntfile.jsexpects sdkjs-forms to be a sibling of sdkjs in the workspace — which is only guaranteed in the DocumentServer superproject checkout.Neither the current AGENTS.md nor the proposed replacement documents this requirement. An agent (or contributor) cloning sdkjs-forms standalone gets silently degraded tooling with no indication why.
What needs doing
Add a brief Checkout section to
AGENTS.md(and toweb-apps/AGENTS.mdwhen that lands) stating:git submodule update --init --recursive).@../AGENTS.md(the shared AI policy and build guide atDocumentServer/AGENTS.md).grunt --addon=sdkjs-formspath resolution also requires this layout.Discovered during review of #5.