@tdk-landscape/tdk-cli-core 1.3.15 → 1.3.26

package/engine/topologies/tilt/common/utils_output.star

@@ -0,0 +1,97 @@
+# =============================================================================
+# 📊 TILT SDK - OUTPUT UTILITIES
+# =============================================================================
+
+
+def print_resource_summary(infra_services, app_resources, should_enable_fn):
+    """Print summary of enabled services and estimated memory usage."""
+    enabled_services = []
+    estimated_memory = 0
+
+    for s in infra_services:
+        if should_enable_fn(s['name']):
+            enabled_services.append(s['name'])
+            svc_memory = s.get('memory')
+            if svc_memory != None:
+                estimated_memory += svc_memory
+            else:
+                estimated_memory += 512  # Default 512MB
+
+    for s in app_resources:
+        if should_enable_fn(s['name']):
+            enabled_services.append(s['name'])
+            svc_memory = s.get('memory')
+            if svc_memory != None:
+                estimated_memory += svc_memory
+            else:
+                estimated_memory += 512  # Default 512MB
+
+    print("\n📊 Resource Summary:")
+    print("  🔧 Enabled services: " + str(len(enabled_services)))
+    print("  💾 Estimated memory: ~" + str(estimated_memory) + "MB")
+
+    if estimated_memory > 4096:
+        print("  ⚠️  WARNING: High memory usage (consider `tilt down && tilt up --focus <domain>`)")
+    elif estimated_memory > 2048:
+        print("  ⚡ MODERATE: Memory usage moderate (use `--focus` to reduce)")
+    else:
+        print("  ✅ OPTIMAL: Memory usage optimized")
+
+    return enabled_services
+
+
+def get_template_header(file_type, generator_name, resource_name='', extra_info=''):
+    """
+    Generate a standardized "DO NOT EDIT" header for auto-generated files.
+    """
+    is_ts_or_js = (
+        file_type.endswith('.ts') or
+        file_type.endswith('.tsx') or
+        file_type.endswith('.js') or
+        file_type.endswith('.jsx') or
+        file_type.endswith('.mjs') or
+        file_type.endswith('.mts')
+    )
+    is_css = file_type.endswith('.css') or file_type.endswith('.scss')
+    is_nginx = file_type.endswith('.conf') or file_type == 'nginx'
+
+    if is_ts_or_js or file_type in ['vite', 'tsconfig', 'typescript', 'javascript']:
+        border = '/' * 79
+        comment_start = '//'
+    elif is_css:
+        border = '/' + '*' * 77 + '/'
+        comment_start = ' *'
+    elif is_nginx or file_type in ['dockerfile', 'compose', 'env', 'shell', 'npmrc', 'bunfig']:
+        border = '#' * 79
+        comment_start = '#'
+    else:
+        border = '#' * 79
+        comment_start = '#'
+
+    resource_line = ''
+    if resource_name:
+        resource_line = '\n{c} Service: {s}'.format(c=comment_start, s=resource_name)
+
+    extra_line = ''
+    if extra_info:
+        extra_line = '\n{c} Type: {e}'.format(c=comment_start, e=extra_info)
+
+    header = """{border}
+{c} 🛑 CRITICAL: SYSTEM-GENERATED FILE - DO NOT MODIFY DIRECTLY
+{c}
+{c} ANY MANUAL CHANGES MADE TO THIS FILE WILL BE WIPED ON THE NEXT 'tilt up'.
+{c} TO MODIFY THIS CONFIGURATION:
+{c} 1. Edit the source generator in: .tilt/topologies/
+{c} 2. Or update service.json
+{c}
+{c} Generation Source: {generator}{resource_line}{extra_line}
+{border}
+""".format(
+        border=border,
+        c=comment_start,
+        generator=generator_name,
+        resource_line=resource_line,
+        extra_line=extra_line,
+    )
+
+    return header

package/engine/topologies/tilt/config/AGENTS.md

@@ -0,0 +1,68 @@
+# AGENTS.md - Global Configuration
+
+## Purpose
+
+Global Tilt configuration, feature flags, environment profiles, and defaults.
+
+## Key Files
+
+### Core Config
+- **`global.star`** - Global configuration loading
+- **`profiles.star`** - Environment profiles (dev, staging, prod)
+- **`features.star`** - Feature flags
+
+### Defaults
+- **`defaults.star`** - Default values for all settings
+- **`overrides.star`** - Local overrides (gitignored)
+
+## Key Concepts
+
+### Configuration Hierarchy
+```
+1. defaults.star        (base values)
+2. profiles.star        (environment-specific)
+3. global.star          (project-wide)
+4. overrides.star       (local user settings)
+5. Environment vars     (runtime)
+```
+
+## Common Tasks
+
+### Get global config
+```starlark
+load("../discovery/config.star", "get_global_config")
+config = get_global_config()
+```
+
+### Check feature flag
+```starlark
+load("./features.star", "is_feature_enabled")
+if is_feature_enabled("nats_streaming"):
+    # Enable NATS
+```
+
+### Get profile
+```starlark
+load("./profiles.star", "get_profile")
+profile = get_profile()  # "pre-alpha", "alpha", "beta", "production"
+```
+
+## Integration
+
+- Loaded by main `Tiltfile`
+- Used by `discovery/config.star`
+- Referenced by `spec.master`
+
+## Important Files
+
+- `spec.master` (project root) - Service-specific defaults
+- `.env` - Local environment variables
+- `tilt_options.json` - Tilt-specific options
+
+## Configuration Values
+
+Common config includes:
+- `MOCK_TIKKIE` - Use mock payment API
+- `FOCUS_*` - Which service groups to load
+- `DB_*` - Database settings
+- `VERDACCIO_*` - NPM registry settings

package/engine/topologies/tilt/config/defaults.star

@@ -0,0 +1,3 @@
+load("../discovery/resource_registry.star", _DEFAULTS_EXPORT = "DEFAULTS_EXPORT")
+
+DEFAULTS = _DEFAULTS_EXPORT

package/engine/topologies/tilt/config/feature_flags.star

@@ -0,0 +1,10 @@
+load("../discovery/resource_registry.star", _DEFAULTS_EXPORT = "DEFAULTS_EXPORT")
+
+def is_enabled(flag_name, cfg, fallback = True):
+    if cfg.get(flag_name) != None:
+        return cfg.get(flag_name)
+    return _DEFAULTS_EXPORT.get(flag_name, fallback)
+
+
+# Inlined constant
+DEFAULTS = {}

package/engine/topologies/tilt/config/global.star

@@ -0,0 +1,55 @@
+# =============================================================================
+# ⚙️ TOPOLOGIES - GLOBAL CONFIG
+# =============================================================================
+
+load("./profiles.star", "Focus")
+load(
+    "../../../../discovery/registry.star",
+    "APP_RESOURCES",
+    "GLOBAL_CONFIG_EXPORT",
+    "INFRA_RESOURCES_EXPORT",
+    "DDD_LIBS_EXPORT",
+    "DEFAULTS_EXPORT",
+    "CORE_INFRA_EXPORT",
+    "INFRA_STACK_MAP_EXPORT",
+    "OPTIONAL_INFRA_EXPORT",
+    "RESOURCE_DEPENDENCIES",
+    "RESOURCE_ALIASES",
+    "RESOURCE_PATH_MAP",
+    "get_platform_libs_export",
+    "get_product_libs_export",
+)
+
+
+def build_config_context():
+    return {
+        "internal_scope": GLOBAL_CONFIG_EXPORT["internal_scope"],
+        "library_roots": GLOBAL_CONFIG_EXPORT["library_roots"],
+        "verdaccio_url_local": GLOBAL_CONFIG_EXPORT["verdaccio_url_local"],
+        "verdaccio_url_docker": GLOBAL_CONFIG_EXPORT["verdaccio_url_docker"],
+        "resource_path_map": RESOURCE_PATH_MAP,
+        "database": GLOBAL_CONFIG_EXPORT["database"],
+    }
+
+
+Config = struct(
+    get_needed_services = Focus.get_needed_services,
+    apply_focus = Focus.apply_focus,
+    create_enabler = Focus.create_enabler,
+    build_context = build_config_context,
+    GLOBAL = GLOBAL_CONFIG_EXPORT,
+    DEFAULTS = DEFAULTS_EXPORT,
+    APP_RESOURCES = APP_RESOURCES,
+    INFRA_RESOURCES = INFRA_RESOURCES_EXPORT,
+    DDD_LIBS = DDD_LIBS_EXPORT,
+    CORE_INFRA = CORE_INFRA_EXPORT,
+    INFRA_STACK_MAP = INFRA_STACK_MAP_EXPORT,
+    OPTIONAL_INFRA = OPTIONAL_INFRA_EXPORT,
+    RESOURCE_DEPENDENCIES = RESOURCE_DEPENDENCIES,
+    RESOURCE_ALIASES = RESOURCE_ALIASES,
+    RESOURCE_PATH_MAP = RESOURCE_PATH_MAP,
+    get_platform_libs = get_platform_libs_export,
+    get_product_libs = get_product_libs_export,
+)
+
+GLOBAL_CONFIG = {}

package/engine/topologies/tilt/config/profiles.star

@@ -0,0 +1,382 @@
+# =============================================================================
+# 🎯 TOPOLOGIES - FOCUS PROFILES
+# =============================================================================
+
+load("../../../topologies/tilt/common/utils.star", "Utils")
+load(
+    "../../../../discovery/registry.star",
+    "APP_RESOURCES",
+    "CORE_INFRA_EXPORT",
+    "INFRA_STACK_MAP_EXPORT",
+    "OPTIONAL_INFRA_EXPORT",
+    "DEFAULTS_EXPORT",
+    "FOCUS_PRE_ALPHA_EXPORT",
+    "FOCUS_ALPHA_EXPORT",
+    "FOCUS_BETA_EXPORT",
+    "get_app_resources",
+    "get_app_resources_ref",
+    "get_resource_aliases_ref",
+    "get_resource_dependencies_ref",
+)
+
+# =============================================================================
+# 🎯 RELEASE PHASE MAPPINGS
+# =============================================================================
+# Map release phase names to service lists from spec.master
+
+RELEASE_PHASES = {
+    "pre-alpha": FOCUS_PRE_ALPHA_EXPORT,
+    "alpha": FOCUS_ALPHA_EXPORT,
+    "beta": FOCUS_BETA_EXPORT,
+}
+
+def expand_release_targets(targets):
+    """Expand release phase targets (pre-alpha, alpha, beta) to service lists."""
+    expanded = []
+    for target in targets:
+        target_lower = target.lower()
+        if target_lower in RELEASE_PHASES:
+            phase_services = RELEASE_PHASES[target_lower]
+            for svc in phase_services:
+                expanded.append(svc)
+        else:
+            expanded.append(target)
+    return expanded
+
+def _get_resources_for_domain(domain_name):
+    """Get resource names (backend, frontend) for a domain from APP_RESOURCES.
+    
+    Returns both the actual service resources and YAML tracking resources.
+    Library resources (appType == 'library') only return YAML resources.
+    
+    Matches by stack name (domain) which is the canonical service identifier.
+    """
+    resources = []
+    for service in get_app_resources_ref():
+        # Match by stack name (domain) - this is the canonical identifier in spec.master
+        service_stack = service.get("stack", "")
+        service_name = service.get("name", "")
+        if service_stack == domain_name or service_name == domain_name:
+            for res in service.get("resources", []):
+                res_name = res.get("name", "")
+                if res_name:
+                    # Check if this is a library resource - libraries don't have runtime resources
+                    manifest = res.get("_manifest", {})
+                    if manifest.get("appType") == "library":
+                        # For libraries, only add YAML tracking resource
+                        resources.append(res_name + "-yaml")
+                    else:
+                        # For actual services (backend, frontend), add both:
+                        # 1. The actual service resource (for docker_build/docker_compose)
+                        resources.append(res_name)
+                        # 2. The YAML tracking resource
+                        resources.append(res_name + "-yaml")
+    return resources
+
+
+def get_all_needed_services(targets, skip_frontend = False):
+    needed = {}
+    visited = {}
+
+    def _resolve_alias(resource_name):
+        if resource_name in get_resource_aliases_ref():
+            alias_value = get_resource_aliases_ref()[resource_name]
+            # get_resource_aliases_ref() maps names to paths (strings), not to resource lists
+            # Only return alias_value if it's a list (of resource names)
+            if type(alias_value) == "list":
+                return alias_value
+        return [resource_name]
+
+    def _filter_frontends(resources, include_frontends):
+        if include_frontends:
+            return resources
+        return [resource for resource in resources if "frontend" not in resource]
+
+    def resolve_target(resource_name):
+        # Explicit focus targets keep their frontends unless --no-frontend is set.
+        return _filter_frontends(_resolve_alias(resource_name), not skip_frontend)
+
+    def resolve_dependency(resource_name):
+        # Transitive domain dependencies should not pull dependency UIs.
+        return _filter_frontends(_resolve_alias(resource_name), False)
+
+    def discover(service):
+        if service in visited:
+            return
+        visited[service] = True
+
+        if skip_frontend and "frontend" in service:
+            return
+
+        needed[service] = True
+
+        deps = get_resource_dependencies_ref().get(service, [])
+        for dep in deps:
+            for resolved in resolve_dependency(dep):
+                discover(resolved)
+
+    for target in targets:
+        for resolved in resolve_target(target):
+            discover(resolved)
+
+    # Expand any domain names in needed to their actual resources
+    # e.g., "identity" -> ["identity-management-backend", "identity-management-frontend", ...]
+    expanded_needed = {}
+    for service in needed:
+        resources = _get_resources_for_domain(service)
+        if resources:
+            for res in resources:
+                expanded_needed[res] = True
+        else:
+            expanded_needed[service] = True
+
+    return expanded_needed.keys()
+
+
+def _load_focus_lists():
+    """Load focus lists from project spec.master directly."""
+    project_root = os.environ.get('TDK_PROJECT_ROOT', '')
+    if not project_root:
+        return ([], [], [])
+    
+    # Load from spec.master
+    spec_paths = [
+        project_root + "/.tdk/.tdk-out/spec.master",
+        project_root + "/spec.master",
+    ]
+    
+    for spec_path in spec_paths:
+        check_cmd = "test -f '{}' && echo 'yes' || echo 'no'".format(spec_path)
+        exists = str(local(check_cmd, quiet=True, echo_off=True)).strip() == 'yes'
+        if exists:
+            # Parse PRE_ALPHA_RESOURCES from spec.master
+            pre_alpha = []
+            alpha = []
+            beta = []
+            
+            content = str(local("cat '" + spec_path + "' 2>/dev/null || true", quiet=True, echo_off=True))
+            
+            # Simple parsing for PRE_ALPHA_RESOURCES = {"key": True, ...}
+            if "PRE_ALPHA_RESOURCES" in content:
+                start = content.find("PRE_ALPHA_RESOURCES = {")
+                if start != -1:
+                    start = content.find("{", start)
+                    end = content.find("}", start)
+                    if start != -1 and end != -1:
+                        dict_content = content[start+1:end]
+                        for line in dict_content.split("\n"):
+                            line = line.strip()
+                            if line and not line.startswith("#"):
+                                # Extract key from "key": True format
+                                if '"' in line or "'" in line:
+                                    quote_char = '"' if '"' in line else "'"
+                                    key_start = line.find(quote_char)
+                                    key_end = line.find(quote_char, key_start + 1)
+                                    if key_start != -1 and key_end != -1:
+                                        key = line[key_start+1:key_end]
+                                        if "True" in line:
+                                            pre_alpha.append(key)
+            
+            if "ALPHA_RESOURCES" in content:
+                start = content.find("ALPHA_RESOURCES = {")
+                if start != -1:
+                    start = content.find("{", start)
+                    end = content.find("}", start)
+                    if start != -1 and end != -1:
+                        dict_content = content[start+1:end]
+                        for line in dict_content.split("\n"):
+                            line = line.strip()
+                            if line and not line.startswith("#"):
+                                if '"' in line or "'" in line:
+                                    quote_char = '"' if '"' in line else "'"
+                                    key_start = line.find(quote_char)
+                                    key_end = line.find(quote_char, key_start + 1)
+                                    if key_start != -1 and key_end != -1:
+                                        key = line[key_start+1:key_end]
+                                        if "True" in line:
+                                            alpha.append(key)
+            
+            if "BETA_RESOURCES" in content:
+                start = content.find("BETA_RESOURCES = {")
+                if start != -1:
+                    start = content.find("{", start)
+                    end = content.find("}", start)
+                    if start != -1 and end != -1:
+                        dict_content = content[start+1:end]
+                        for line in dict_content.split("\n"):
+                            line = line.strip()
+                            if line and not line.startswith("#"):
+                                if '"' in line or "'" in line:
+                                    quote_char = '"' if '"' in line else "'"
+                                    key_start = line.find(quote_char)
+                                    key_end = line.find(quote_char, key_start + 1)
+                                    if key_start != -1 and key_end != -1:
+                                        key = line[key_start+1:key_end]
+                                        if "True" in line:
+                                            beta.append(key)
+            
+            return (pre_alpha, alpha, beta)
+    
+    return ([], [], [])
+
+
+def apply_focus_filter(cfg):
+    # Ensure discovery is complete before applying focus filter
+    if len(get_app_resources_ref()) == 0:
+        get_app_resources()
+
+    focus_targets = cfg.get("focus", [])
+
+    # Default to pre-alpha if no focus targets specified
+    if not focus_targets:
+        print("🎯 Mode: pre-alpha (use --focus for alpha/beta)")
+        focus_targets = ["pre-alpha"]
+
+    parsed_targets = []
+    for target in focus_targets:
+        parsed_targets.extend(target.split(","))
+    parsed_targets = [t.strip() for t in parsed_targets if t.strip()]
+    
+    # Load focus lists directly from spec.master (since env var is set after module load)
+    pre_alpha_list, alpha_list, beta_list = _load_focus_lists()
+    
+    # Temporarily override RELEASE_PHASES with loaded values
+    dynamic_phases = {
+        "pre-alpha": pre_alpha_list if pre_alpha_list else FOCUS_PRE_ALPHA_EXPORT,
+        "alpha": alpha_list if alpha_list else FOCUS_ALPHA_EXPORT,
+        "beta": beta_list if beta_list else FOCUS_BETA_EXPORT,
+    }
+    
+    # Expand release phase targets (pre-alpha, alpha, beta) to service lists
+    expanded = []
+    for target in parsed_targets:
+        target_lower = target.lower()
+        if target_lower in dynamic_phases:
+            phase_services = dynamic_phases[target_lower]
+            for svc in phase_services:
+                expanded.append(svc)
+        else:
+            expanded.append(target)
+    parsed_targets = expanded
+
+    if not parsed_targets:
+        return (False, None, None)
+
+    print("🎯 ═══════════════════════════════════════════════════════════════")
+    print("🎯  UBER-STYLE FOCUS MODE ACTIVATED")
+    print("🎯  Target services: " + ", ".join(parsed_targets))
+    print("🎯 ═══════════════════════════════════════════════════════════════")
+
+    skip_frontend = cfg.get("no-frontend", False)
+    include_monitoring = cfg.get("include-monitoring", False)
+
+    needed_list = get_all_needed_services(parsed_targets, skip_frontend)
+    needed = {}
+    for s in needed_list:
+        needed[s] = True
+
+    for infra in CORE_INFRA_EXPORT:
+        needed[infra] = True
+        if infra in INFRA_STACK_MAP_EXPORT:
+            needed[INFRA_STACK_MAP_EXPORT[infra]] = True
+
+    if include_monitoring:
+        needed["monitoring"] = True
+        for svc in OPTIONAL_INFRA_EXPORT.get("monitoring", []):
+            needed[svc] = True
+
+    if os.environ.get("INFISICAL_ENABLED", "true").lower() == "true":
+        needed["infisical"] = True
+        for svc in OPTIONAL_INFRA_EXPORT.get("infisical", []):
+            needed[svc] = True
+
+    for target in parsed_targets:
+        if target in get_resource_aliases_ref():
+            needed[target] = True
+
+    all_needed = needed.keys()
+
+    logic_toggles = [
+        "database-management",
+        "golden-image",
+        "proxy",
+        "verdaccio",
+        "infisical",
+        "monitoring",
+        "elk",
+        "debezium",
+        # Domains are auto-discovered from service manifests
+        # No hardcoded domain names - all from service.json
+        "backends-only",
+    ]
+    # Infrastructure resources that exist as Tilt local_resource or docker_compose
+    # These are handled separately and should not be in resource_only_needed
+    infra_resource_names = CORE_INFRA_EXPORT + ["infisical-db", "infisical-redis"]
+    for opt_infra_list in OPTIONAL_INFRA_EXPORT.values():
+        for res in opt_infra_list:
+            if res not in infra_resource_names:
+                infra_resource_names.append(res)
+    
+    # config.set_enabled_resources accepts only concrete Tilt resources.
+    # Logic toggles (e.g. "golden-image", "database-management") are excluded since they're config flags, not resources.
+    # Infrastructure resources (postgres, nats, traefik, etc.) are loaded via Infra.load_all()
+    # and excluded here since they may not be available in all projects.
+    # Only include resources that exist as discovered services (in resource aliases).
+    resource_aliases = get_resource_aliases_ref()
+    resource_only_needed = []
+    for r in all_needed:
+        if r in logic_toggles:
+            continue
+        if r not in resource_aliases:
+            continue
+        resource_only_needed.append(r)
+
+    print("🎯 Discovered " + str(len(all_needed)) + " entities via dependency graph:")
+
+    app_resources = [r for r in all_needed if any([x in r for x in ["backend", "frontend", "migrator"]])]
+    infra_resources = [r for r in all_needed if r in CORE_INFRA_EXPORT or any([r in v for v in OPTIONAL_INFRA_EXPORT.values()])]
+    db_resources = [r for r in all_needed if "provision-db" in r]
+
+    if app_resources:
+        print("   📱 Apps: " + ", ".join(sorted(app_resources)))
+    if db_resources:
+        print("   🗃️  Databases: " + ", ".join(sorted(db_resources)))
+    if infra_resources:
+        print("   🏗️  Infrastructure: " + ", ".join(sorted(infra_resources)))
+
+    print("🎯 ═══════════════════════════════════════════════════════════════")
+
+    return (True, all_needed, resource_only_needed)
+
+
+def create_should_enable_wrapper(focus_mode, focus_enabled_all, cfg, defaults):
+    def should_enable_wrapper(resource_name):
+        if focus_mode and focus_enabled_all:
+            # Check if resource_name itself is in the list (for infrastructure)
+            if resource_name in focus_enabled_all:
+                return True
+            # Check if resource_name starts with any domain in focus_enabled_all
+            # e.g., "identity-management-backend" starts with "identity"
+            for domain in focus_enabled_all:
+                if resource_name.startswith(domain + "-"):
+                    return True
+            # Check get_resource_aliases_ref() (if it maps to resource lists)
+            if resource_name in get_resource_aliases_ref():
+                alias_value = get_resource_aliases_ref()[resource_name]
+                if type(alias_value) == "list":
+                    return any([res in focus_enabled_all for res in alias_value])
+            return False
+        return Utils.should_enable(resource_name, cfg, defaults)
+
+    return should_enable_wrapper
+
+
+Focus = struct(
+    get_needed_services = get_all_needed_services,
+    apply_focus = apply_focus_filter,
+    create_enabler = create_should_enable_wrapper,
+)
+
+
+# Inlined constant
+DEFAULTS = {}

package/engine/topologies/tilt/generators/agents_md.star

@@ -0,0 +1,62 @@
+# =============================================================================
+# 🤖 TILT SDK - AGENTS.MD GENERATOR (free-tier stub)
+# =============================================================================
+# Path: .tilt/providers/generators/agents_md.star
+# =============================================================================
+# The full AI-agent guard rails (the multi-section AGENTS.md explaining the
+# manifest-driven architecture, the do/don't table, and the emergency
+# override procedure) are a paid TDK feature. When a valid license grants
+# the "agents-md" resource, cli/src/generator/template-engine.ts
+# (vendorTdkExtension) overwrites this file with the licensed version
+# fetched via extension-fetch.ts before Tilt loads it. Same function
+# signature either way, so nothing else in the generator pipeline changes.
+# =============================================================================
+
+
+# === INLINED CONSTANTS for pure extension loading ===
+OUTPUT = struct(AUTOGENERATED_FOLDER = ".autogenerated")
+# === END INLINED CONSTANTS ===
+
+
+load('../../../topologies/tilt/common/utils.star', 'Utils')
+
+_STUB_NOTICE = """# ⚠️ AUTOGENERATED FILES - DO NOT MODIFY
+
+**This folder (`.autogenerated/`) contains MACHINE-GENERATED files.** Any changes you make here will be overwritten the next time Tilt runs the configuration generators.
+
+Full AI-agent guard rails (architecture explanation, do/don't table, emergency override procedure) are a paid TDK feature. Run `tdk upgrade` to enable the complete generated AGENTS.md for this service.
+"""
+
+
+def generate_agents_md(manifest, write_fn=None):
+    """
+    Free-tier stub - see module header. Signature matches the licensed
+    implementation so callers never need to know which one is active.
+    """
+    resource_path = manifest.get('_resource_path', '')
+    app_name = manifest.get('appName', 'unknown-service')
+    app_type = manifest.get('appType', 'backend')
+
+    header = Utils.get_template_header(
+        'agents_md',
+        'AgentsMd.generate() [unlicensed stub]',
+        app_name,
+        'Output: .autogenerated/AGENTS.md',
+    )
+
+    content = header + _STUB_NOTICE
+
+    if write_fn:
+        output_path = resource_path + '/' + OUTPUT.AUTOGENERATED_FOLDER + '/AGENTS.md'
+        write_fn(output_path, content)
+
+    return content
+
+
+# =============================================================================
+# 🎯 PUBLIC API
+# =============================================================================
+
+AgentsMd = struct(
+    generate = generate_agents_md,
+)