Initial curated ITWorx_MCP_Hub source from 368fba691ea8d23403b4d56b53b5ec670d7c5020

catalog/README.md

@@ -0,0 +1,26 @@
+# Declarative catalog
+
+This directory is the desired-state source for ITWorx MCP Hub. Catalog documents use **JSON-compatible YAML**: every `.yaml` file is valid YAML 1.2 and also valid JSON. This deliberate restriction lets the design pack validate the catalog using only Python's standard library before `uv`, PyYAML, or application dependencies exist.
+
+## Reconciliation rules
+
+1. Parse and validate every document against `contracts/schemas/`.
+2. Normalize slugs and endpoint aliases.
+3. Resolve template references without reading secrets.
+4. Calculate a deterministic desired-state hash.
+5. Produce a preview with create/update/disable/no-op actions.
+6. Reject destructive or privilege-expanding drift unless the active policy permits it.
+7. Apply through the ContextForge adapter and Hub repositories.
+8. Read back actual state and compare it with desired state.
+9. Record an append-only audit event and reconciliation evidence.
+
+Catalog files never contain credentials. They contain references such as `docker-secret://gitea_mcp_token` or `authentik-client://itworx-mcp-hub`.
+
+## Verification states
+
+- `verified`: discovered and tested against the real target;
+- `unverified`: plausible desired state that must not be reported as live;
+- `external-input-required`: implementation is complete but a credential, URL, or target mapping is unavailable;
+- `fake-only`: deterministic fake is the current test binding.
+
+The initial project files intentionally use discovery placeholders. `WP-145` replaces only facts it can prove and retains explicit placeholders for everything else.