ivy-readme-assemble

name	ivy-readme-assemble
description	Assemble final README from precomputed fragments and write to target path.
argument-hint	<target-readme-path>
user-invocable	true

Ivy README Assemble

Assemble README from fragment inputs without recomputation.

Inputs

• targetReadme (required): output path
• fragments (required): precomputed markdown fragments
• templateRef (optional): template/schema path
• styleProfile (optional): formatting profile inferred from repository docs

Behavior

1. Read template order and output-format.md for fallback rules.
2. For each fragment:
   • If status is success or partial: inject content verbatim.
   • If status is partial and content is synthesized, inject the content with a note indicating it was auto-generated.
   • Example: "This section was auto-generated based on available data."
   • If status is missing or content is empty: keep section heading and inject a bullet-prefixed fallback line. Default fallback: - No information was delivered for this section.
     • Components-specific fallbacks (mandatory): when injecting missing subsections under ## Components, emit targeted bullet sentences instead of the generic fallback. Use these exact sentences:
       • Callable Subprocesses missing -> - For this market extension we do not provide any callable subprocesses.
       • Dialog Components missing -> - For this market extension we do not provide any dialog components.
       • Rest Clients missing -> - For this market extension we do not provide any rest clients.
       • Web Services missing -> - For this market extension we do not provide any web services.
       • Maven Artifacts missing -> - For this market extension we do not provide any maven artifacts.
     • Rest Clients acceptance gate (mandatory): evaluate ### Rest Clients only from restClientsSection (extracted from config/rest-clients.yaml). Do not treat openApiSection as Rest Clients evidence.
   • Web Services acceptance gate (mandatory): evaluate ### Web Services only from webServicesSection (extracted from config/webservice-clients.yaml). Do not treat openApiSection as Web Services evidence.
   • Validate fragment quality before injection: reject pseudo-filled content (e.g., generic placeholders without extracted structure) and normalize to missing with the default fallback.
   • If requiredSubsections is provided, verify each subsection appears in content; for missing entries, append explicit placeholder lines under the correct section.
   • If preserveMode=verbatim, do not rewrap, renumber, or normalize markdown blocks.
   • If preserveMode!=verbatim, normalize ordered-list sequence before injection:
     • Detect broken list numbering (for example repeated top-level 1. items).
     • Renumber sequentially by indentation level so top-level steps render as 1., 2., 3. and nested steps stay nested.
     • Do not alter fenced code blocks, inline code, links, or image paths.
   • Resolve heading aliases from styleProfile and inject into the repository-native heading without changing the fragment content.

• Demo section: Inject demoIntroSection directly under ## Demo. Always render heading ### Demo Workflows after demoIntroSection, then inject demoWorkflows fragment content (or fallback if missing).

• Setup section: Assemble in order: Roles → OpenAPI → Variables block reference → [Setup steps].

• Roles placement: Insert as bullet point at start of Setup section (before steps): - **Roles:** ...

• OpenAPI placement: Insert as bullet point WITHIN Setup section (not separate ## Components section): - **OpenAPI:** Spec URL

  • If openApiSection is missing or empty, render exactly: - **OpenAPI:** No information was delivered for this section.
  • Canonical Rest Clients mapping (mandatory): render ### Rest Clients from restClientsSection content (extracted from config/rest-clients.yaml). This mapping is canonical and must be applied consistently across models.

• Canonical Web Services mapping (mandatory): render ### Web Services from webServicesSection content (extracted from config/webservice-clients.yaml). This mapping is canonical and must be applied consistently across models.

• Variables placement: Inject under ## Setup as ### Variables subsection (not standalone section) unless style profile explicitly requests standalone.

• Image placement: If an image fragment is present with standalone=false, place image snippets in the target sections indicated by fragment placement hints (for example intro/demo/setup). If productImageSection status is missing or empty, do NOT create a standalone ## Images section. Instead, skip image section entirely. All images must be embedded within their related content sections (Setup, Demo, etc.).

  • Image embedding algorithm (required, step-aware for per-workflow demo images):

    Algorithm Overview: For each image in :

Example:

If an image has placement: demo:workflow-Document Splitting, assembler must find the ##### Document Splitting workflow block in the Demo section and insert the image after the numbered steps for that workflow.

If an image has placement: demo:workflow-Document Splitting:step-2, assembler must insert the image directly below step 2. in that workflow.

• Critical image rule: Do not create a standalone ## Images section under any circumstances unless the template or fragment explicitly sets standalone=true. When productImageSection is missing/empty, simply omit the entire Images section from output — do not insert a fallback placeholder like "No images detected".
• Components hierarchy rule: Always render ## Components and place ### Callable Subprocesses, ### Dialog Components, ### Rest Clients, ### Web Services, and ### Maven Artifacts beneath it.
• Never render ## Callable Subprocesses as top-level heading.
• Variables missing rule: Under ### Variables, if variablesSection is missing/empty, do not inject fallback text.

3. Never omit a section heading from the template. The assembler MUST always render heading ### Demo Workflows after demoIntroSection, even if the demoWorkflows fragment is missing or empty.
4. Remove unnecessary HTML comments (e.g., <!-- status: ... -->) from fragment content before injection. Never include timestamps, skill names, or other metadata in the final output.
5. Preserve the exact fenced variable block containing @variables.yaml@ if present.
6. Apply styleProfile when present to keep repository-native markdown conventions (ordered list style, OpenAPI style, callable-sub layout). 6.1 Prefer repository-native section placement when style profile indicates it (e.g., variables inside setup).
7. Write assembled result to target path.

• Use full-file overwrite semantics (truncate then write complete assembled content).
• Do not append to existing README content.
• After write, validate duplicate safety: exactly one full-document start (# ...) should exist. If duplicate full-document starts are found, rewrite the file once with the same assembled content.

Fragment validation rules

• Mandatory fragments: productDescriptionSection, keyFeatures, demoIntroSection, demoWorkflows, rolesSection, openApiSection, setupSection, variablesSection, callableSubSection, formComponentSection, restClientsSection, webServicesSection, mavenArtifactSection
• Optional fragments: productImageSection
• Acceptance validation: restClientsSection and webServicesSection must be validated independently from openApiSection; OpenAPI setup evidence does not satisfy Components coverage.
• Treat content as pseudo-filled if it only states availability (e.g., "present in file", "see process file") without extracted details required by that section.
• Pseudo-filled content must be normalized to missing and rendered with explicit fallback text.
• Normalization must preserve section headings and template order.
• Roles and OpenAPI must be presented as inline bullet points in Setup, NOT as separate sections.

Quality criteria

• No scanning in this step.
• No paraphrasing or reformatting of fragments.
  • Heading order follows the README Template Format in output-format.md strictly. The assembler MUST always render sections in this order, regardless of fragment extraction order:
    1. Product description (productDescriptionSection)
    2. Key features (keyFeatures)
    3. Demo (demoIntroSection, then heading ### Demo Workflows, then demoWorkflows)
    4. Setup (rolesSection, openApiSection, variablesSection)
    5. Components (### Callable Subprocesses from callableSubSection, ### Dialog Components from formComponentSection, ### Rest Clients from restClientsSection, ### Web Services from webServicesSection, ### Maven Artifacts from mavenArtifactSection)
  • If any fragment is missing, inject the fallback placeholder at the correct position.
• Must keep all template headings even when fragment data is missing.
• Must never read from or mutate approved README.md during assembly.
• Must report subsection coverage gaps before writing final output.
• Must not pass through ambiguous placeholder prose as successful extraction output.