Choose the layer that matches the job
Portable Core owns operation metadata and the existing defineCommand, defineQuery, defineEvent and defineCapability constructors. It also owns feature composition, versioned references and documentation references. Start here to describe a reusable domain boundary. The compatibility package forwards established paths to canonical owners; it remains useful when reading older consumers. A registry, renderer, provider implementation or installed product capability is a separate part of the composition. The current README describes this ownership extraction as staged, so follow the selected release context when deciding what a consumer can adopt.
Write the contract before the transport
Describe one concrete action or read: its key, version, input, output, error outcomes and declared policy. Identify any emitted event and its relationship to the operation. Put related operations behind a capability, then use a feature to describe the larger composition and its dependencies. Keep documentation close to the definition and reference it explicitly. The source docs.generate operation is a useful complete specimen because its operation, capability requirement and colocated DocBlock can be inspected together.
Preserve identity while navigating the repository
The same contract may be reachable through a canonical leaf and a historical forwarding path. Compare the selected package export maps before creating a second declaration or duplicating a registry. Treat document revision, operation version and package version as separate identifiers. When a contract changes, inspect its callers, event consumers, presentation bindings and examples. A renamed source folder is an ownership change; it should not silently become a new semantic operation or erase an existing versioned reference.
Follow a practical path.
Trace one complete operation
Open the definition and record its exact key/version, input and output model, policy and event references. Follow the implementation registration into a runtime package, then the host adapter. This establishes which parts are declarative and which part handles a real request.
Extend a feature deliberately
List the operation, event, capability and presentation references that the feature actually needs. Reuse their canonical identities and keep optional dependencies visible. Compare a nearby maintained feature rather than guessing a new reference shape.
Check the consumer boundary
Choose the package and subpath available in the intended release, inspect its forwarding relationship, and run the owning project’s existing validation in that environment. Record the result separately from the fact that a source declaration exists.