External Examples Repository Integration

1. Status

This decision is Accepted. ocean-examples is registered as a git submodule of Ocean-Atlas, and builders/core treats it as a distinct content source from canonical Markdown.

2. Context

Ocean examples are complete, runnable projects: DSL source files, generation configuration, and — for each example — an example-info/example-info.html explanation. They are validated by actually generating and running them, which is a different lifecycle and a different toolchain from writing a concept page or a DSL reference.

Keeping example projects inside the main Ocean-Atlas repository would tie their commit history, issue tracking, and validation pipeline to a knowledge-documentation repository that has none of the tooling required to build or run them. It would also make Ocean-Atlas responsible for reviewing and versioning full DSL projects, not just the documents that describe them.

3. Decision

Runnable examples are maintained in the separate ocean-examples repository and are pulled into Ocean-Atlas as a git submodule at ocean-examples/, declared in .gitmodules:

[submodule "ocean-examples"]
    path = ocean-examples
    url = git@github.com:gilmardcom/ocean-examples.git

builders/core treats the submodule as a distinct content source, not as ordinary canonical Markdown:

• an example’s ocean-examples/<slug>/example.md is classified as "example", not "canonical", and is built into a NormalizedExample by buildExamples — a separate model from NormalizedDocument;
• every other file inside ocean-examples/ (the .ocn sources, the example-info/example-info.html explanation, diagrams, fixtures) is classified as "project" and is read directly by the example pipeline, not treated as a standalone canonical document;
• the repository-level ocean-examples/index.md supplies the content for the canonical examples.index catalog page.

CI checks out the submodule with authenticated access, since ocean-examples is a private repository.

4. Alternatives Considered

4.1 Store example projects directly inside Ocean-Atlas

Rejected. It would mix a documentation repository’s review and release cadence with a DSL project’s build-and-run validation cadence, and would require Ocean-Atlas’s own CI to carry the Ocean toolchain needed to generate and execute every example.

4.2 Treat examples as ordinary canonical Markdown

Rejected. An example is not one Markdown document; it is a project with many source files plus one explanatory document. Folding it into the generic canonical-document model would either lose the executable files or force builders/core’s generic discovery and validation rules to understand DSL project structure, which is out of scope for a presentation-independent knowledge builder (see adr.atlas-builder-boundary).

4.3 Reference examples by external link only, with no local copy

Rejected. Without a local, versioned copy, Ocean-Atlas could not validate the example descriptor and relationships, extract Horizon and Voyage, inventory the implementation files, or pin the exact independently validated example revision that matches the published explanation.

4.4 A package-manager dependency instead of a git submodule

Considered. A published package would require its own registry and release process for what is, at this stage, a single closely-coupled companion repository. A git submodule keeps the relationship explicit, pins an exact commit, and needs no additional publishing infrastructure.

5. Consequences

Benefits

• Example projects are versioned, reviewed, and validated independently of Ocean-Atlas’s own documentation review cycle.
• Ocean-Atlas pins an exact ocean-examples commit, so the published catalog only changes when that pin is deliberately updated.
• ocean-examples’s own toolchain (compiling and running the DSL) never needs to run inside builders/core.

Trade-offs

• Cloning Ocean-Atlas requires a submodule checkout (git submodule update --init), and CI needs authenticated access to a private repository — an additional setup step contributors and pipelines must get right.
• The published example catalog can silently go stale if the submodule pin is not updated, since updating Ocean-Atlas’s own Markdown does not update the pinned example commit.
• Two repositories, two histories: understanding why an example changed sometimes requires looking at ocean-examples’s own commit log.

6. Implementation Implications

• builders/core’s discoverExampleDirectories and buildExamples (builders/core/src/examples.ts) are the only supported way to turn ocean-examples content into published pages; the presentation adapter must not read ocean-examples/ directly.
• Bumping the submodule pin is the only way to publish example changes; editing files inside ocean-examples/ from within an Ocean-Atlas checkout does not update the canonical pin.
• CI must authenticate the submodule checkout before any step that runs builders/core discovery or the Astro build.

7. Validation and Compliance Rules

• An example directory without example.md is not published — see discoverExampleDirectories, which only publishes a source directory once it has an Atlas descriptor.
• An example’s example.md ID must equal examples.<usage.id>, matching the identifier declared in its OCEAN-EXAMPLE-META block, or the build fails.
• An example must contain at least one .ocn (DSL) file, or example validation fails.
• Example relationship targets must resolve against known canonical or example IDs, the same as canonical document relationships.

8. Related Knowledge

• adr.atlas-builder-boundary — the Core/adapter boundary that the example pipeline also respects.
• adr.example-knowledge-facets — what an example’s example.md and example-info.html are each responsible for once discovered.
• examples.index — the published catalog this integration produces.

These semantic relationships are declared in the document metadata.