Restructure v0.9 and v0.10 catalog files into dedicated catalog directories

[jacobsimionato]

Currently, our catalog files (basic and minimal) for v0.9 and v0.10 reside in the generic specification/vX_X/json/ directory alongside the core protocol schemas.

To improve modularity and organization, we need to restructure the minimal and basic catalogs (and their examples) into a dedicated catalogs/ hierarchy.

Important: This change should only apply to v0.9 and v0.10. The v0.8 specification must remain untouched for backward compatibility.

Proposed Structure (for both v0.9 and v0.10):

• specification/v0_9/catalogs/basic/catalog.json (formerly basic_catalog.json)
• specification/v0_9/catalogs/basic/rules.txt (formerly basic_catalog_rules.txt)
• specification/v0_9/catalogs/basic/examples/
• specification/v0_9/catalogs/minimal/catalog.json (formerly minimal_catalog.json)
• specification/v0_9/catalogs/minimal/examples/
• specification/v0_9/catalogs/minimal/README.md

Acceptance Criteria:

1. File Moves: Relocate the basic and minimal catalogs, rules, and example directories for v0.9 and v0.10 to the new structure.
2. Schema Updates: Update internal $id, $ref, and catalogId properties within the JSON schemas to reflect the new paths. (e.g. https://a2ui.org/specification/v0_9/catalogs/basic/catalog.json).
3. Example Updates: Update the catalogId references in all example JSON files.
4. Tooling & SDK Updates:
   • Update agent_sdks/python/src/a2ui/basic_catalog/constants.py (for v0.9/v0.10).
   • Update specification/scripts/validate.py.
   • Update tools/build_catalog/assemble_catalog.py.
   • Update renderers/web_core/package.json and renderers/web_core/scripts/copy-spec.js.
5. Documentation & Hosting:
   • Update mentions in @docs/** (like renderer_guide.md, a2ui_protocol.md, catalogs.md).
   • Update .github/workflows/docs.yml to ensure that the new catalogs/ directory structure is copied and hosted correctly on the documentation site so that URLs like https://a2ui.org/specification/v0_9/catalogs/basic/catalog.json resolve correctly.
   • Set up backward compatibility copying in the docs workflow if necessary so existing links don't immediately break.

Note to Implementer:
Before implementing, please perform a fresh repository-wide search (e.g., using grep or codebase search) for basic_catalog.json, minimal_catalog.json, v0_9/json, and v0_10/json. This is crucial to catch any new references or examples that may have been merged recently.

[jacobsimionato]

Coding agent prompt:

This task requires restructuring the catalog JSON schemas and examples for A2UI versions 0.9 and 0.10. Do NOT touch v0.8.

Implementation Strategy

1. Pre-flight Search:
   Run search commands across the workspace to find all references to the old paths before making changes.

   • grep -rn "v0_9/json/basic_catalog.json" .
   • grep -rn "v0_10/json/basic_catalog.json" .
   • grep -rn "minimal_catalog.json" .
   • grep -rn "v0_9/json/catalogs" .

2. File System Restructuring:
   For both v0_9 and v0_10 directories in @specification/:

   • Create directories: catalogs/basic/ and catalogs/minimal/.
   • Move json/basic_catalog.json -> catalogs/basic/catalog.json.
   • Move json/basic_catalog_rules.txt -> catalogs/basic/rules.txt.
   • Move json/catalogs/basic/examples/ -> catalogs/basic/examples/.
   • Move json/catalogs/minimal/minimal_catalog.json -> catalogs/minimal/catalog.json.
   • Move json/catalogs/minimal/examples/ -> catalogs/minimal/examples/.
   • Move json/catalogs/minimal/README.md -> catalogs/minimal/README.md.
   • Remove the old json/catalogs/ directories.

3. Update JSON Schemas and Examples:

   • In the new catalog.json files, update $id and catalogId to match the new URI structure (e.g., https://a2ui.org/specification/v0_9/catalogs/basic/catalog.json).
   • Fix internal $ref pointers. Relative paths to common_types.json will need to change from ../common_types.json to ../../json/common_types.json.
   • Update all catalogId strings inside the JSON files within the examples/ directories.

4. Update Python SDK:

   • Modify @agent_sdks/python/src/a2ui/basic_catalog/constants.py to update the paths for v0.9 (and v0.10 if present). Keep v0.8 exactly as it is.

5. Update Tooling & CI:

   • Validation Script: Update @specification/scripts/validate.py configs for v0_9 (and v0_10) to reflect the new root_schema, refs, and examples glob paths.
   • Assembler: Update BASIC_CATALOG_URLS and INTERCEPT_MAP in @tools/build_catalog/assemble_catalog.py.
   • Web Core Renderer: Update wireit.copy-spec.files in @renderers/web_core/package.json to include the nested catalog JSONs, and adjust @renderers/web_core/scripts/copy-spec.js to recursively copy the new catalog structure into the dist/src folders.
   • Docs Workflow: Update @.github/workflows/docs.yml. Ensure the Copy schemas to documentation step preserves the new catalogs/ structure. Add fallback cp commands to place catalog.json into the legacy flat root (docs/specification/v0_9/basic_catalog.json) to prevent breaking existing external links during the transition.

6. Update Documentation:

   • Search through @docs/ and update references to basic_catalog.json and minimal_catalog.json. Key files include @docs/concepts/catalogs.md, @specification/v0_9/docs/a2ui_protocol.md, and @specification/v0_9/docs/renderer_guide.md.

Edge Cases to Handle

• Ensure that the Web Core build process (copy-spec.js) successfully flattens or maintains directory structure as required by tsc. If the TypeScript code imports basic_catalog.json directly, update those import paths in the TypeScript source as well.
• Be careful with tools/build_catalog/assemble_catalog.py alias logic mapping basic_catalog.json to catalog.json.

Testing Requirements

• Run python specification/scripts/validate.py to ensure all examples still pass JSON schema validation.
• Run npm run build in renderers/web_core/ to ensure the TypeScript build can still find and copy the schemas.
• Run the Python SDK tests uv run pytest inside agent_sdks/python/ to ensure the SDK still resolves the basic catalog correctly.