Read the contract the framework exposes
A useful guide explains a decision and shows the API shape behind it. Copying that shape into another document creates another place to maintain it.
Wildo marks selected contracts in source and extracts them into the delivered references. The guide supplies the explanation; the excerpt supplies the declaration and its package origin.
Example — Wire a new module
The module guide explains where the module belongs in the application. Its reference brings together the application configuration contract and the shared module interface, so the agent can connect the two.
For engineers
Author the explanation and reference the contract
This is the framework’s authored framework-new-module-wiring-api.md reference. The placeholders are compiler inputs, not syntax to put into an application resource:
# New module — config & shared shape (source)
- Declare the module under **`modules`** in `wildo.saas.config.ts` (`ApplicationModulesSchema`).
- Implement the shared-lib slice as **`SharedSaaSModule`** (resources, relationships, optional product/feature/milestone hooks).
{{REFERENCE:platform.config.application-modules}}
{{REFERENCE:saas.models.shared-saas-module}}
Each topic identifies registered source spans. During generation, the compiler extracts those spans, removes the source markers and emits fenced code with package provenance. A topic can collect more than one relevant span.
Understand the shape without duplicating it
The shared module contract begins with these members. This reduced source excerpt omits later members of SharedSaaSModule:
export interface SharedSaaSModule extends SharedDomainModule {
moduleId: string;
kind?: ApplicationModuleKind;
customRoles?: RolesConfiguration;
customFeatureDefinitions?: FeatureDefinitionWithAutoRegister[];
// Further configuration members omitted from this excerpt.
}
The declaration explains the module identity and extension hooks; the guide explains which of them a particular change needs. The application imports the public contract through its package entry point and supplies its own module values.
Keep generation and installation connected
An extracted reference reflects the source used to generate that package. Editing framework code does not instantly update a previously installed guide. Framework maintainers regenerate the payload; application builders refresh the installed assets after updating the relevant package.
The integrity audit checks whether the topic and its references connect correctly. Compilation and behavior checks answer whether the demonstrated usage works. Both matter, because a resolvable excerpt and a correct application change are different results.