Document how to add and extend upstream workflow templates

[vitormattos]

Context

LibreCode keeps organization workflow templates in this repository.

The repository already documents the upstream workflow model, immutable vendoring, patches, rendering, validation, and automated refresh. However, it does not yet give a clear contributor procedure for adding a new upstream workflow or extending an existing one.

A contributor should not need to design the workflow catalog architecture before making a small catalog change.

Goal

Extend the existing workflow documentation with a clear, step-by-step contract for adding and maintaining workflow templates derived from Nextcloud.

The documentation must describe the current architecture. Do not create a new workflow distribution model.

Document the two supported cases

1. Add a new upstream workflow

Document the exact expected flow:

1. add the upstream source to upstream/sources.json;
2. pin the source to an immutable upstream commit and SHA-256;
3. store the vendored source under upstream/vendor/nextcloud/;
4. add the rendered template definition to upstream/templates.json;
5. add local template metadata when required;
6. add a LibreCode patch only when the organization needs a real difference from upstream;
7. render the template with the existing renderer;
8. run the existing source, render, policy, and repository tests.

Explain that the generated file under workflow-templates/ is an output of this process and must stay reproducible from the vendored source plus declared patches.

2. Extend an existing upstream workflow

Document that contributors must:

1. keep the vendored upstream workflow unchanged;
2. add or update the matching file under patches/nextcloud/;
3. keep patches small and focused on LibreCode requirements;
4. render the template again;
5. review the generated workflow;
6. run the normal validation;
7. update the patch when a future upstream refresh no longer applies cleanly.

Ownership rules

Document where changes belong:

• upstream behavior stays in the vendored upstream workflow;
• reusable LibreCode changes belong in patches/nextcloud/;
• generated organization workflows belong in workflow-templates/;
• application-specific changes belong in the consumer repository;
• consumer-only workflow differences should use the consumer .yml.patch mechanism instead of being added to the organization template.

Also document that application runtime setup should normally live in the application test/bootstrap code when it is not a generic CI concern.

Required examples

Add one small example for:

• adding a new upstream-derived workflow;
• adding one LibreCode patch to an existing workflow;
• deciding that a change must stay in the consumer repository.

The examples must use generic names. Do not add product-specific workflow behavior only for the documentation example.

Commands

Document the existing commands used to:

• verify vendored upstream sources;
• refresh upstream sources;
• render templates;
• run the related tests and workflow policy checks.

Use the repository's existing scripts. Do not add a second tool or manual copy procedure.

Scope

Update the existing workflow documentation instead of creating a separate architecture.

Do not:

• redesign the catalog;
• introduce reusable workflow callers;
• change the synchronization model;
• change credential policy;
• change dependency update policy;
• add a new workflow as part of this issue.

Done when

• A contributor can add a new upstream-derived workflow without designing the catalog architecture.
• The upstream source, patch, rendered template, and consumer patch responsibilities are explicit.
• The documented commands match the scripts already present in the repository.
• Examples cover add, extend, and consumer-only customization.
• Existing repository validation passes.

Good first issue

This is a documentation-only task. The architecture and required content are defined above. Keep the change focused on making the existing workflow model easier to follow.