Complete WP-0010: HTTP remote federation with cache

Extend federation manifest schema for url sources with auth and TTL metadata.
Fetch remote capability indexes over HTTP(S), cache under
registry/federation/cache/, and fall back to stale cache on fetch failure.
Add --refresh flag, seven federation tests, and updated federation docs.

reuse_surface/cli.py

@@ -146,7 +146,7 @@ def cmd_overlaps(args: argparse.Namespace) -> int:
 
 def cmd_federation_compose(args: argparse.Namespace) -> int:
     try:
-        target, warnings = write_federated_index()
+        target, warnings = write_federated_index(refresh=args.refresh)
     except (FileNotFoundError, ValueError) as exc:
         print(f"error: {exc}", file=sys.stderr)
         return 1
@@ -258,6 +258,11 @@ def main(argv: list[str] | None = None) -> int:
     )
     federation_sub = federation.add_subparsers(dest="federation_command", required=True)
     compose = federation_sub.add_parser("compose", help="compose federated index")
+    compose.add_argument(
+        "--refresh",
+        action="store_true",
+        help="bypass remote index cache and refetch URL sources",
+    )
     compose.set_defaults(func=cmd_federation_compose)
 
     query = subparsers.add_parser("query", help="query capability index")