Technical Advisory

Dispatcher Technical Advisory (Cloud)

Provide deterministic guidance for AEMaaCS use cases involving the Adobe Dispatcher Apache HTTP Server module and related HTTPD configuration.

Variant Scope

• This skill is cloud-service-only.
• Scope is fixed by this skill directory; do not ask the user to choose deployment variant.

MCP Tool Contract

Use only these Dispatcher MCP tools when producing verification plans:

• validate
• lint
• sdk
• trace_request
• inspect_cache
• monitor_metrics
• tail_logs

Workflow

1. Confirm scope and assumptions. 2. If the repo layout or execution path is unclear, start with quick-start-execution-path.md and repo-layout-workflows.md. 3. Apply cloud-service-aemaacs-guardrails.md to lock immutable/include constraints, validator-enforced topology checks (symlinks/aliases/includes), reserved probe-path behavior, and CDN-vs-Dispatcher boundaries. 4. Use capability-coverage-map.md to route prompt/tool/resource intents to the right dispatcher skill flow. 5. Select a scenario path from core7-capability-playbook.md for development/debugging requests. 6. Convert the selected playbook to exact MCP commands with playbook-command-linkage.md. 7. For conceptual questions (e.g. statfileslevel, filter order, URL decomposition, cache invalidation), use concepts.md and cite official docs. 8. Use curated public references for recommendations in this variant. 9. Produce MCP verification steps for this variant when needed. 10. Route execution-heavy changes to this variant's execution skills.

Verification Scope Selection

Use shared references for deterministic coverage:

• mode-specific-verification-matrix.md
• test-case-catalog.md

Output Contract

Use one of these output shapes:

• Explanation-only question: recommendation summary + citation list from curated public-docs index.
• Recommendation/change question: recommendation summary + citation list + MCP verification plan with expected evidence + risk/rollback guidance and open risks.

Guardrails

• Do not claim a check was executed unless tool evidence exists.
• Keep variant assumptions explicit for every recommendation.
• For migration/cross-variant requests, produce a side-by-side variant delta plan from the verification matrix and flag when the companion variant plugin must be run separately.
• Follow citation discipline from public-doc-citation-rules.md.
• Keep cloud-service-only guardrails explicit: immutable/default include contracts and CDN-vs-Dispatcher ownership.

References

• core7-capability-playbook.md – high-value development/debugging playbooks for the current core-7 MCP contract
• capability-coverage-map.md – prompt/tool/resource coverage map to current dispatcher skill workflows
• quick-start-execution-path.md – single entry path for broad or first-time requests
• repo-layout-workflows.md – normalize repos to the dispatcher src root and likely file families
• playbook-command-linkage.md – deterministic linkage from playbooks to MCP commands and tests
• cloud-service-aemaacs-guardrails.md – cloud-service-only immutable/include/runtime boundary checks from AEMaaCS patterns
• concepts.md – key concepts (filter last-match, URL decomposition, statfileslevel, invalidate vs flush) for explanations
• public-docs-index.md
• public-doc-citation-rules.md
• mode-specific-verification-matrix.md
• test-case-catalog.md
• change-risk-and-rollback-template.md
• core-7-tools-reference.md
• request-router.md

Change Risk And Rollback Template

Use this template for any dispatcher recommendation that changes behavior.

1) Change Summary

• Change scope:
• Target mode: cloud
• Files impacted:
• User-visible impact expected:

2) Risk Assessment

3) Blast Radius

• Hostnames/farms affected:
• URL classes affected:
• Dependency assumptions:

4) Rollback Plan

• Rollback trigger criteria:
• Immediate rollback action:
• Validation after rollback:
• Owner/escalation path:

5) Verification Gate

The change is production-ready only when:

1. Required checks in mode-specific-verification-matrix.md are complete. 2. Evidence is attached for each executed check. 3. Open risks are explicitly accepted or remediated.

AEMaaCS Cloud Guardrails (Core-7)

Use this checklist before proposing or applying Dispatcher/HTTPD changes in AEMaaCS.

This guardrail is grounded in current cloud dispatcher configuration layouts, validator behavior, managed runtime defaults, and dispatcher/httpd semantics.

1) Source-Of-Truth Layout And Ownership

Treat dispatcher/src as the deployable config root (must contain conf.d and conf.dispatcher.d).

Do not edit cloud-managed defaults directly. Put customer intent in mutable wrappers:

• conf.d/rewrites/rewrite.rules (includes default rewrite rules)
• conf.dispatcher.d/filters/filters.any (includes default filters)
• conf.dispatcher.d/cache/rules.any (includes default cache rules)
• conf.dispatcher.d/clientheaders/clientheaders.any (includes default clientheaders)
• conf.dispatcher.d/virtualhosts/virtualhosts.any (includes default virtualhosts)
• custom conf.d/available_vhosts/*.vhost and conf.dispatcher.d/available_farms/*.farm

Treat these wrapper files as extension points, not replacement excuses. Preserve the include of the managed default unless there is a deliberate, evidence-backed reason to override the baseline:

• conf.d/rewrites/rewrite.rules should keep default_rewrite.rules
• conf.dispatcher.d/filters/filters.any should keep default_filters.any
• conf.dispatcher.d/cache/rules.any should keep default_rules.any
• conf.dispatcher.d/clientheaders/clientheaders.any should keep default_clientheaders.any
• conf.dispatcher.d/virtualhosts/virtualhosts.any should keep default_virtualhosts.any

Treat these as cloud-managed defaults whose semantics should be preserved unless platform documentation explicitly says otherwise:

• conf.d/dispatcher_vhost.conf
• conf.dispatcher.d/dispatcher.any
• conf.d/available_vhosts/default.vhost
• conf.dispatcher.d/available_farms/default.farm
• cloud-managed safety vhosts and unmatched-host catch-all behavior in conf.d/dispatcher_vhost.conf

2) Required Cloud Topology Invariants

Keep these invariants intact for validator compatibility:

• conf.dispatcher.d/dispatcher.any includes enabled_farms/*.farm
• conf.d/dispatcher_vhost.conf includes conf.d/enabled_vhosts/*.vhost
• conf.d/enabled_vhosts/*.vhost and conf.dispatcher.d/enabled_farms/*.farm are symlinks
• farm includes remain in known locations:
• /clientheaders -> ../clientheaders/clientheaders.any
• /virtualhosts -> ../virtualhosts/virtualhosts.any
• /renders -> ../renders/default_renders.any
• /filter -> ../filters/filters.any
• /cache/rules -> ../cache/rules.any
• /cache/allowedClients -> ../cache/default_invalidate.any
• /cache/ignoreUrlParams -> ../cache/marketing_query_parameters.any or a wrapper file at the validator-supported customer include location

If include topology changes, require explicit validator proof.

3) Validator-Enforced Contracts

For cloud readiness, assume these checks are mandatory:

• must find at least one enabled farm (conf.dispatcher.d/enabled_farms/*.farm)
• must find at least one enabled vhost (conf.d/enabled_vhosts/*.vhost)
• include targets must match known include locations (unknown include paths fail)
• ServerName "*" is invalid and fails validation
• filename/symlink/file-size checks are part of full
• ServerAlias "*.adobeaemcloud.net" and ServerAlias "*.adobeaemcloud.com" are expected; currently warnings but treat as release blockers

Typical failure signatures seen in validator testdata:

• missing farm: unable to find any farm in 'conf.dispatcher.d/enabled_farms'
• missing vhost: no file found for matching pattern: conf.d/enabled_vhosts/*.vhost
• bad include location: included file (...) does not match any known file
• bad ServerName: ServerName directive is set to '*'
• invalid statfileslevel: Statfileslevel set to -1... misconfiguration

Important cloud warning to treat as action item:

• if /ignoreUrlParams is not configured, validator warns about marketing parameter strategy

4) Reserved Runtime Paths And Rewrite Safety

Do not repurpose or rewrite over cloud-managed health and probe paths:

• /system/probes/live
• /system/probes/start
• /system/probes/ready
• /system/probes/health
• /systemready

dispatcher_vhost.conf wires these paths for liveness, startup, readiness, and managed rewrite-map rollout behavior. Any vhost or rewrite customization must preserve their pass-through behavior and must not introduce redirects, auth gates, or filter denials on those endpoints.

When managed rewrite maps are enabled, readiness behavior depends on the rewrite-map readiness state. Do not assume redirect maps are active before readiness conditions are met.

Preserve cloud-managed vhost safety behavior as well:

• customer vhosts are included explicitly via conf.d/enabled_vhosts/*.vhost
• cloud-managed safety vhosts may exist ahead of customer vhosts
• an unmatched-host catch-all exists to avoid leaking customer site behavior to arbitrary hostnames

Do not remove or bypass these guards unless the user is intentionally working on those specific cloud-runtime behaviors and the change is validated end to end.

5) Runtime And Variable Assumptions

• prefer cloud variables (for example ${DOCROOT}, ${AEM_IP}) over hardcoded absolute paths
• avoid local-host assumptions in deployable files
• separate local-only SDK execution paths from final cloud config content

Preserve these cloud defaults unless the change explicitly requires otherwise and the impact is proven:

• AllowEncodedSlashes NoDecode
• ModMimeUsePathInfo On
• DirectorySlash Off
• DispatcherUseProcessedURL On
• DispatcherPassError 0
• DispatcherUseForwardedHost may be controlled by platform-provided configuration; treat host-forwarding behavior as a trust-boundary setting
• DispatcherRestrictUncacheableContent On

Preserve managed defaults in these extension surfaces unless the user is intentionally changing the feature:

• default_clientheaders.any forwards critical headers such as Authorization, Cookie, Host, X-Forwarded-Proto, and x-request-id
• default_filters.any carries supported allow rules for CSRF token fetches, GraphQL, persisted queries, Forms, Screens, clientlibs, and selected commerce-related routes
• default_rules.any keeps known deny cache rules such as CSRF token responses and Screens channel JSON
• default_rewrite.rules includes protections such as X-Forwarded-For spoof blocking, common abusive path blocking (xmlrpc.php, wp-login), and the persisted-query ;.json pass-through rewrite used for cache file extension compatibility

Managed runtime behavior to respect:

• CACHE_GRAPHQL_PERSISTED_QUERIES requires matching CORS and endpoint verification when enabled
• default.farm enables serveStaleOnError, gracePeriod, and enableTTL by default; tune them deliberately, not accidentally

Cloud-managed environment-sensitive routes also exist:

• development-only and product-feature routes may be enabled by environment
• Commerce GraphQL endpoints, frontend-static passthrough, and Dynamic Media delivery paths may have dedicated proxy or no-rewrite handling in the cloud baseline

Do not classify these as unconditional vulnerabilities. Evaluate them by environment and by whether the behavior is intentional for the documented cloud baseline.

Design implication: do not depend on trace-level logging for production diagnostics.

6) CDN vs Dispatcher Decision Boundary

Use Dispatcher/HTTPD for:

• filter rules, cache rules, vhost/rewrite routing near AEM
• request handling that depends on farm/filter/cache semantics

Use CDN configuration for:

• edge traffic filtering, WAF, rate limiting
• CDN-native redirect/error-page and edge cache policy concerns

When both are possible, document why one layer is chosen.

7) Cloud Preflight Verification (Core-7)

Minimum static evidence before sign-off:

1. validate({"config":"<changed dispatcher content>","type":"cloud"}) 2. lint({"mode":"directory","target":"<dispatcher src path>","strict_mode":true}) 3. sdk({"action":"check-files","config_path":"<dispatcher src path>"}) 4. sdk({"action":"diff-baseline","config_path":"<dispatcher src path>"}) for drift-sensitive changes

When a local dispatcher validator is available, corroborate with:

• validator full <dispatcher-src>
• validator httpd <dispatcher-src>
• validator dispatcher <dispatcher-src>

When local SDK runtime verification is required, use local-sdk-execution.md to record the launcher mode and any non-default environment variables that affect local behavior.

Runtime evidence when behavior changed:

• trace_request({"url":"<representative url>","config_path":"<dispatcher src path>"})
• inspect_cache({"url":"<representative cacheable url>","config_path":"<dispatcher src path>"})

Also verify these cloud-specific invariants when relevant:

• reserved probe paths still bypass custom rewrites/redirects
• platform-managed safety vhosts and unmatched-host behavior remain intact
• custom vhosts still provide the required adobeaemcloud.net and adobeaemcloud.com alias coverage
• query-parameter cache strategy is explicit if cache behavior changed
• GraphQL persisted-query caching changes include matching CORS verification
• default client header forwarding is still sufficient for the feature set in use
• default rewrite protections and supported product endpoint rewrites remain intact unless intentionally replaced

8) Output Expectations For Cloud Recommendations

Always include:

• explicit cloud assumption (AEMaaCS)
• whether immutable/default include contracts were impacted
• whether concern belongs to Dispatcher layer or CDN layer
• which validator/lint/runtime checks were executed vs skipped
• residual risk if runtime proof was not available

Reference docs:

• Cloud Dispatcher overview: https://experienceleague.adobe.com/en/docs/experience-manager-cloud-service/content/implementing/content-delivery/disp-overview
• Validation/debugging and file rules: https://experienceleague.adobe.com/en/docs/experience-manager-cloud-service/content/implementing/content-delivery/validation-debug
• Traffic filter rules / WAF: https://experienceleague.adobe.com/en/docs/experience-manager-cloud-service/content/security/traffic-filter-rules-including-waf
• CDN overview: https://experienceleague.adobe.com/en/docs/experience-manager-cloud-service/content/implementing/content-delivery/cdn

Core-7 Tools Reference

This document defines the shared MCP tool contract used by the dispatcher skills.

Overview

The core-7-tools contract is the baseline tool set for dispatcher work across both AEMaaCS and AMS variants.

The contract exists to keep dispatcher skills:

• deterministic
• auditable
• variant-aware
• constrained to a stable, reviewable execution surface

Tool Catalog

validate

Purpose:

• syntax and structure validation for dispatcher and HTTPD config fragments

Use when:

• authoring or reviewing .any, vhost, rewrite, cache, or filter changes
• checking config before runtime verification

Common patterns:

• dispatcher section validation
• HTTPD/vhost block validation
• variant-specific validation modes such as ams or cloud

lint

Purpose:

• best-practice analysis across security, performance, ordering, and maintainability concerns

Use when:

• filter order matters
• release gates or security gates are required
• config quality matters beyond raw syntax validity

Common patterns:

• lint(strict) for release or security gates
• lint(deep) for filter, cache, and ordering-heavy changes

sdk

Purpose:

• file-level integrity checks, baseline drift analysis, and SDK-backed validation helpers

Use when:

• include topology matters
• immutable/default drift matters
• local project or validator-backed evidence is needed

Common patterns:

• sdk(check-files)
• sdk(diff-baseline)
• optional deeper validation helpers when the environment supports them

trace_request

Purpose:

• trace effective routing and decision flow for a representative request

Use when:

• debugging 403, 5xx, redirect loops, host routing, or rewrite behavior
• proving expected allow or deny outcomes

Common patterns:

• failing URL versus healthy URL comparison
• canonical redirect checks
• host and method-sensitive routing checks

inspect_cache

Purpose:

• inspect cacheability, cache state, and metadata for representative URLs

Use when:

• tuning cache rules
• debugging cache misses, stale content, or invalidation scope
• checking auth-sensitive cache behavior

monitor_metrics

Purpose:

• capture operational signals such as status-code mix, latency shifts, or hit-ratio changes

Use when:

• triaging incidents
• comparing before/after tuning evidence
• quantifying impact windows

tail_logs

Purpose:

• collect concrete runtime evidence from dispatcher or HTTPD logs

Use when:

• an incident needs real examples instead of only static reasoning
• cache or redirect behavior needs corroboration
• a request trace needs supporting log evidence

Contract Rules

All dispatcher skills that declare mcp-tool-contract: core-7-tools should follow these rules:

1. Prefer the smallest sufficient command chain. 2. Do not claim a tool was run unless evidence exists. 3. Distinguish observation from inference. 4. Use static checks first unless the task is runtime-first by nature. 5. Keep variant assumptions explicit (ams vs cloud). 6. Report skipped checks and why they were skipped.

Selection Guidance

Use this progression unless a specialist playbook says otherwise:

1. validate 2. lint 3. sdk 4. trace_request 5. inspect_cache 6. tail_logs 7. monitor_metrics

Not every task needs all seven tools. The contract defines the allowed baseline, not a mandatory full run.

Failure And Troubleshooting Patterns

When a tool fails or cannot be used:

• validate failure:
• report the exact failing block and error text
• do not continue as if the config is structurally sound
• lint failure or warning set:
• separate hard blockers from advisory findings
• keep ordering and security warnings explicit
• sdk(check-files) failure:
• treat include topology, immutable-file drift, or missing-file issues as high-signal structural problems
• trace_request unavailable:
• fall back to static rule analysis and state the confidence limit clearly
• inspect_cache unavailable:
• use static cache reasoning plus any available log or metric signals
• tail_logs unavailable:
• avoid claiming runtime confirmation
• monitor_metrics unavailable:
• avoid quantifying impact improvements or regressions

Variant Notes

• The tool contract is shared across variants.
• The meaning of success differs by variant because guardrails differ.
• Always pair the tool outputs with the relevant variant guardrails and verification matrix.

Local Dispatcher SDK Execution (Cloud)

Use this reference when cloud dispatcher work requires a local SDK-backed runtime, not just static validation.

This file documents the launcher contract exposed by the shipped Dispatcher SDK scripts. It aligns with Set up Dispatcher Tools (Adobe Experience League): Dispatcher is run locally using Docker against the src Dispatcher and Apache Web server configuration files. Treat the help output from the installed SDK package as the final authority for your exact SDK version.

When To Use This

Use local SDK execution when you need one of these:

• container-backed runtime verification for rewrites, filters, vhosts, cache behavior, or probe-path handling
• local test mode to confirm the processed config and basic HTTPD/dispatcher validity
• hot-reload feedback while iterating on dispatcher config changes

Do not confuse this with deployable cloud config content. These commands are local runtime helpers.

Positional Contract

The shipped launcher usage is:

./bin/docker_run.sh <dispatcher-src> <aem-host>:<aem-port> <local-port>
./bin/docker_run.sh <dispatcher-src> <aem-host>:<aem-port> test

Common examples (first argument is the path to the Dispatcher configuration src folder):

./bin/docker_run.sh ./src <aem-host>:4503 8080
DISP_RUN_MODE=stage ./bin/docker_run.sh ./src <aem-host>:4503 8080
DISP_LOG_LEVEL=trace1 ./bin/docker_run.sh ./src <aem-host>:4503 8080
REWRITE_LOG_LEVEL=trace2 ./bin/docker_run.sh ./src <aem-host>:4503 8080
./bin/docker_run.sh ./src <aem-host>:4503 test

For an AEM project, point to the project's dispatcher/src folder (e.g. ~/code/my-project/dispatcher/src).

Meaning of the positional arguments:

• <dispatcher-src>: path to the Dispatcher configuration src folder (e.g. SDK's ./src or project's dispatcher/src). The launcher runs against these config files; there is no separate "out" deployment folder.
• <aem-host>:<aem-port>: backend AEM endpoint the local Dispatcher runtime should talk to
• <local-port>: host port that exposes the local Dispatcher runtime
• test: run config test mode instead of exposing a live local port

Hot reload

Hot reload lets the container pick up changes to Dispatcher and Apache config files without restarting the container—useful when iterating on rewrites, filters, vhosts, or other config under <dispatcher-src>.

Preferred: hot-reload launcher

Many SDK packages include a dedicated launcher:

./bin/docker_run_hot_reload.sh <dispatcher-src> <aem-host>:<aem-port> <local-port>

It uses the same positional contract as docker_run.sh but watches the config src folder and reloads when files change. Prefer this when available; if your SDK prints different usage, follow its help output.

Fallback: HOT_RELOAD with standard launcher

If docker_run_hot_reload.sh is not present, some SDK versions support hot reload via the standard launcher and the HOT_RELOAD environment variable:

HOT_RELOAD=true ./bin/docker_run.sh ./src <aem-host>:<aem-port> 8080

Check your SDK version; when supported, config changes under the src folder are picked up without restarting. See Runtime Environment Variables for the HOT_RELOAD variable details.

Runtime Environment Variables

The shipped launcher help exposes these environment variables:

DISP_RUN_MODE

Defines the simulated environment type for the local run.

Valid values:

• dev
• stage
• prod

Default is dev.

DISP_LOG_LEVEL

Sets dispatcher log verbosity.

Valid values:

• trace1
• debug
• info
• warn
• error

Default is warn.

Use trace1 when you need backend request flow or dispatcher decision detail.

REWRITE_LOG_LEVEL

Sets rewrite-engine log verbosity.

Valid values:

• trace1 through trace8
• debug
• info
• warn
• error

Default is warn.

Use this when debugging RewriteRule and RewriteCond behavior.

ENV_FILE

Imports variables from a file before startup.

Use this when local SDK execution depends on variables that would otherwise be exported manually.

HOT_RELOAD

Enables config reload when watched files in the config src folder change (no container restart).

Valid values:

• true
• false

Default is false.

Use this for local iteration loops on rewrites, filters, and vhosts. When your SDK does not provide docker_run_hot_reload.sh, try HOT_RELOAD=true with docker_run.sh if the package supports it. See Hot reload for usage.

ALLOW_CACHE_INVALIDATION_GLOBALLY

Overwrites the default invalidation behavior to allow all connections for cache invalidation.

Valid values:

• true
• false

Default is false.

Treat this as a local test convenience only. Do not carry this posture into production guidance.

HTTPD_DUMP_VHOSTS

Enables vhost dump output for debugging.

Valid values:

• true
• false

Default is false.

ENABLE_MANAGED_REWRITE_MAPS_FLAG

Enables managed rewrite maps.

Valid values:

• true
• false

Default is true.

This matters when local behavior depends on rewrite-map-backed redirects or readiness gating.

MANAGED_REWRITE_MAPS_PROBE_CHECK_SKIP

Skips probe checks for managed rewrite maps.

Valid values:

• true
• false

Default is false.

Only use this when intentionally isolating local rewrite-map behavior and call out that the check was skipped.

Host-Side Compatibility Variable

You may also see:

export DOCKER_API_VERSION=1.43

This is a host Docker-client compatibility override, not a dispatcher runtime setting. Use it only when the installed SDK scripts or local Docker environment require it.

Recommended Execution Patterns

1. Static Config Test

Use this first when the goal is syntax or processed-config validation:

./bin/docker_run.sh ./src <aem-host>:<aem-port> test

Use this before claiming runtime behavior is verified.

2. Live Local Dispatcher Port

Use this when you need request/response verification:

./bin/docker_run.sh ./src <aem-host>:<aem-port> 8080

Then verify behavior with representative requests against the local port.

3. Hot Reload Iteration

Use this when tuning rewrites, filters, or vhosts repeatedly so config changes apply without restarting the container. See Hot reload for the launcher and HOT_RELOAD fallback.

./bin/docker_run_hot_reload.sh ./src <aem-host>:<aem-port> 8080

If your SDK does not include docker_run_hot_reload.sh, use HOT_RELOAD=true ./bin/docker_run.sh ./src <aem-host>:<aem-port> 8080 when supported.

Skill Usage Guidance

When using local SDK execution in cloud dispatcher skills:

• state whether evidence came from static validation, local SDK runtime, or MCP runtime tools
• record the exact launcher mode used: live port, hot reload, or test
• record any non-default env vars that materially changed behavior
• call out when managed rewrite map checks, invalidation safety, or run-mode simulation could affect the conclusion
• do not treat local SDK behavior as stronger evidence than executed MCP/runtime evidence against the actual target environment

Cloud Verification Matrix

Use this matrix to select the minimum acceptable verification set for cloud mode.

How To Use

1. Pick the change or incident type. 2. Execute required static checks. 3. Execute runtime checks when behavior is runtime-sensitive. 4. Record evidence in the skill output contract.

Verification Matrix (cloud)

Skip Rules

You may skip runtime checks only when runtime prerequisites are unavailable. If skipped, state:

• exactly which checks were skipped
• why they were skipped
• what remains unverified
• what environment is required to complete verification

Examples

Example 1: Filter Rule Change

Scenario: Add allow rule for /content/site/api/* with GET method only.

# Static checks
lint({"mode":"directory","target":"/path/to/dispatcher/src","strict_mode":true})
sdk({"action":"check-files","config_path":"/path/to/dispatcher/src"})
validate({"config":"<dispatcher.any content>","type":"cloud"})

# Runtime verification
trace_request({
  "url": "/content/site/api/products.json",
  "method": "GET",
  "config_path": "/path/to/dispatcher/src"
})

Example 2: Cache Behavior Investigation

Scenario: Investigate why /content/site/en.html is not caching as expected.

inspect_cache({"url":"/content/site/en.html","config_path":"/path/to/dispatcher/src"})
monitor_metrics({"window_minutes":10,"breakdown_by":"status_code"})
tail_logs({"lines":100,"filter_cache_status":"MISS"})

Example 3: Cloud Readiness Validation

Scenario: Validate config works in cloud mode.

validate({"config":"<dispatcher.any content>","type":"cloud"})
lint({"mode":"directory","target":"/path/to/dispatcher/src","strict_mode":true})
sdk({"action":"check-files","config_path":"/path/to/dispatcher/src"})
sdk({"action":"diff-baseline","config_path":"/path/to/dispatcher/src"})

Common Issues Found:

• hardcoded container paths
• Docker-specific directive mistakes
• include graph and filter logic regressions
• missing ServerAlias "*.adobeaemcloud.net" / "*.adobeaemcloud.com" coverage
• missing /ignoreUrlParams strategy for marketing/query parameter cache control
• custom rewrites intercepting /systemready or /system/probes/*
• dropped managed default includes or header forwarding causing feature regressions

Playbook To MCP Command Linkage (Cloud Dispatcher)

Use this file after selecting a playbook. It turns the playbook choice into a deterministic MCP command chain with expected evidence.

Config Authoring Playbooks

Incident Response Playbooks

Security Playbooks

Performance Playbooks

Command Usage Notes

• Use validate(dispatcher) as shorthand for a dispatcher-targeted validate(...) call with the relevant merged config section.
• Use validate(httpd) as shorthand for an Apache/vhost-targeted validate(...) call with the relevant vhost or rewrite block.
• Use lint(strict) for release-gate or security-gate reviews; use lint(deep) when rule ordering or cache policy nuance matters.
• If runtime prerequisites are missing, run the available static commands, report the gap, and leave the runtime tests open.

Public Doc Citation Rules

Use these rules for all Cloud dispatcher advisory responses.

Allowed Sources

• Use links listed in public-docs-index.md.
• Use only Experience League references (cloud mode docs + common Dispatcher docs).
• Do not cite sources unavailable to external readers in public skill guidance.

Citation Requirements

For non-trivial recommendations, include:

1. at least one common Dispatcher source 2. at least one cloud-specific source when behavior differs by mode

Topic-To-Citation Minimums

Use these minimum citation sets for precision and consistency:

• Filter ordering / allow-deny conflicts:
• Dispatcher content filter docs
• Dispatcher security checklist
• statfileslevel / invalidation scope:
• Dispatcher invalidation by folder level docs
• Dispatcher cache flush/invalidation docs
• URL decomposition / selector-suffix logic:
• Dispatcher content filter docs
• Cloud validation/debug docs when recommendation depends on include/file layout constraints
• Rewrite behavior / redirects:
• Dispatcher configuration docs
• Cloud Dispatcher overview or pipeline-free redirect docs (pick claim-aligned source)
• Cache headers / TTL strategy:
• Dispatcher caching docs
• AEMaaCS caching docs
• Cloud immutable/include/validator compatibility:
• AEMaaCS validation/debug docs
• Cloud Dispatcher overview docs
• CDN vs Dispatcher ownership decisions:
• AEMaaCS CDN docs
• Cloud Dispatcher overview docs

Citation Format

Use a compact list:

• Title - URL - one-line relevance note

Claim Discipline

• Distinguish observed MCP evidence from documentation guidance.
• If docs and runtime evidence conflict, state the conflict and prioritize executed evidence for environment-specific conclusions.
• For version-sensitive claims, include release-notes citation when available.

Prohibited Patterns

• Unsupported claims without citations.
• Ambiguous mixed-mode guidance without mode labels.
• Copying large verbatim excerpts from external docs.

Public Docs Index (Dispatcher Source Of Truth)

Use this file as the curated public reference set for Cloud Dispatcher guidance.

Dispatcher Core (Common Experience League)

• Dispatcher overview: https://experienceleague.adobe.com/en/docs/experience-manager-dispatcher/using/dispatcher
• Dispatcher FAQ: https://experienceleague.adobe.com/en/docs/experience-manager-dispatcher/using/troubleshooting/dispatcher-faq
• Dispatcher install: https://experienceleague.adobe.com/en/docs/experience-manager-dispatcher/using/getting-started/dispatcher-install
• Dispatcher configuration: https://experienceleague.adobe.com/en/docs/experience-manager-dispatcher/using/configuring/dispatcher-configuration
• Content filter config: https://experienceleague.adobe.com/en/docs/experience-manager-dispatcher/using/configuring/dispatcher-configuration#configuring-access-to-content-filter
• Caching docs: https://experienceleague.adobe.com/en/docs/experience-manager-dispatcher/using/configuring/dispatcher-configuration#caching-documents
• Cache invalidation: https://experienceleague.adobe.com/en/docs/experience-manager-dispatcher/using/configuring/dispatcher-configuration#invalidating-files-by-folder-level
• Flush from AEM: https://experienceleague.adobe.com/en/docs/experience-manager-dispatcher/using/configuring/dispatcher-configuration#invalidating-dispatcher-cache-from-aem
• Dispatcher domains: https://experienceleague.adobe.com/en/docs/experience-manager-dispatcher/using/configuring/dispatcher-domains
• Dispatcher SSL: https://experienceleague.adobe.com/en/docs/experience-manager-dispatcher/using/configuring/dispatcher-ssl
• Permissions cache: https://experienceleague.adobe.com/en/docs/experience-manager-dispatcher/using/configuring/permissions-cache
• Page invalidate patterns: https://experienceleague.adobe.com/en/docs/experience-manager-dispatcher/using/configuring/page-invalidate
• Dispatcher troubleshooting: https://experienceleague.adobe.com/en/docs/experience-manager-dispatcher/using/troubleshooting/dispatcher-troubleshooting
• Security checklist: https://experienceleague.adobe.com/en/docs/experience-manager-dispatcher/using/getting-started/security-checklist
• Dispatcher release notes: https://experienceleague.adobe.com/en/docs/experience-manager-dispatcher/using/getting-started/release-notes
• Dispatcher CSRF hardening: https://experienceleague.adobe.com/en/docs/experience-manager-dispatcher/using/configuring/configuring-dispatcher-to-prevent-csrf

AEMaaCS Dispatcher (Cloud)

• Cloud Dispatcher overview: https://experienceleague.adobe.com/en/docs/experience-manager-cloud-service/content/implementing/content-delivery/disp-overview
• Content delivery overview: https://experienceleague.adobe.com/en/docs/experience-manager-cloud-service/content/implementing/content-delivery/overview
• Cloud Dispatcher migration notes: https://experienceleague.adobe.com/en/docs/experience-manager-cloud-service/content/implementing/content-delivery/disp-overview#migrating
• Validation and debugging: https://experienceleague.adobe.com/en/docs/experience-manager-cloud-service/content/implementing/content-delivery/validation-debug
• Validation and debugging (legacy): https://experienceleague.adobe.com/en/docs/experience-manager-cloud-service/content/implementing/content-delivery/validation-debug-legacy
• Local Dispatcher Tools setup: https://experienceleague.adobe.com/en/docs/experience-manager-learn/cloud-service/local-development-environment-set-up/dispatcher-tools
• Caching in AEMaaCS: https://experienceleague.adobe.com/en/docs/experience-manager-cloud-service/content/implementing/content-delivery/caching
• Edge Side Includes (ESI): https://experienceleague.adobe.com/en/docs/experience-manager-cloud-service/content/implementing/content-delivery/edge-side-includes
• CDN overview: https://experienceleague.adobe.com/en/docs/experience-manager-cloud-service/content/implementing/content-delivery/cdn
• CDN traffic configuration: https://experienceleague.adobe.com/en/docs/experience-manager-cloud-service/content/implementing/content-delivery/cdn-configuring-traffic
• CDN credentials/authentication: https://experienceleague.adobe.com/en/docs/experience-manager-cloud-service/content/implementing/content-delivery/cdn-credentials-authentication
• Pipeline-free redirects: https://experienceleague.adobe.com/en/docs/experience-manager-cloud-service/content/implementing/content-delivery/pipeline-free-url-redirects
• CDN cache purge: https://experienceleague.adobe.com/en/docs/experience-manager-cloud-service/content/implementing/content-delivery/cdn-cache-purge
• CDN error pages: https://experienceleague.adobe.com/en/docs/experience-manager-cloud-service/content/implementing/content-delivery/cdn-error-pages
• Traffic filter rules / WAF: https://experienceleague.adobe.com/en/docs/experience-manager-cloud-service/content/security/traffic-filter-rules-including-waf
• Advanced networking: https://experienceleague.adobe.com/en/docs/experience-manager-cloud-service/content/security/configuring-advanced-networking
• IMS support: https://experienceleague.adobe.com/en/docs/experience-manager-cloud-service/content/security/ims-support
• Cloud release notes: https://experienceleague.adobe.com/en/docs/experience-manager-cloud-service/content/release-notes/home
• AMS hosted on AEMaaCS architecture: https://experienceleague.adobe.com/en/docs/experience-manager-cloud-service/content/implementing/content-delivery/ams-aem

Cloud Caching Tutorials (Experience League Learn)

• Caching overview: https://experienceleague.adobe.com/en/docs/experience-manager-learn/cloud-service/caching/overview
• Author-tier caching: https://experienceleague.adobe.com/en/docs/experience-manager-learn/cloud-service/caching/author
• Publish-tier caching: https://experienceleague.adobe.com/en/docs/experience-manager-learn/cloud-service/caching/publish
• CDN cache hit ratio analysis: https://experienceleague.adobe.com/en/docs/experience-manager-learn/cloud-service/caching/cdn-cache-hit-ratio-analysis
• Enable caching (how-to): https://experienceleague.adobe.com/en/docs/experience-manager-learn/cloud-service/caching/how-to/enable-caching
• Disable caching (how-to): https://experienceleague.adobe.com/en/docs/experience-manager-learn/cloud-service/caching/how-to/disable-caching
• Purge cache (how-to): https://experienceleague.adobe.com/en/docs/experience-manager-learn/cloud-service/caching/how-to/purge-cache

Key Concepts

• Filter evaluation: last applied rule wins (see content filter docs).
• URL decomposition for all URL-based rules (filters, cache rules): use path/selectors/extension/suffix; in filters use (/path, /selectors, /extension, /suffix) from Dispatcher configuration docs.

Question-To-Doc Mapping

• Filter conflict/order questions:
• Content filter config
• Security checklist
• CSRF mitigation questions:
• Dispatcher CSRF hardening
• Content filter config
• statfileslevel / invalidation blast-radius questions:
• Cache invalidation by folder level
• Flush from AEM
• URL decomposition / selector-suffix questions (filters, cache rules):
• Content filter config
• Caching docs
• Validation and debugging
• Rewrite/redirect behavior questions:
• Dispatcher configuration
• pipeline-free redirects
• Cache headers / TTL / CDN behavior questions:
• Caching in AEMaaCS
• Dispatcher caching docs
• Cache operations questions (enable/disable/purge):
• Enable caching (how-to)
• Disable caching (how-to)
• Purge cache (how-to)
• Cloud WAF or traffic filtering questions:
• Traffic filter rules / WAF
• CDN overview
• Cloud immutable/include/validator-compatibility questions:
• Validation and debugging
• Validation and debugging (legacy)
• Cloud Dispatcher overview
• ESI and fragment composition questions:
• Edge Side Includes (ESI)
• Content delivery overview
• CDN vs Dispatcher ownership questions:
• CDN overview
• Cloud Dispatcher overview

Usage Policy

1. Use only Experience League links listed in this file. 2. Keep recommendations scoped to cloud mode. 3. If docs and MCP runtime evidence conflict, state the conflict and prioritize executed evidence for environment-specific conclusions.

Quick Start Execution Path (Cloud Dispatcher)

Use this file when the user is new to the dispatcher skills, asks for "start to finish" help, or provides a broad request such as "set up dispatcher for this feature" or "audit and fix the config."

In this skill set, "Dispatcher" means the Adobe Dispatcher Apache HTTP Server module plus its HTTPD/dispatcher configuration, not an AEM OSGi bundle.

Fast Entry Checklist

1. Normalize the config root to the dispatcher src directory. 2. Confirm the target hostnames, paths, methods, and cache/auth expectations. 3. Classify the change as one of:

• config implementation
• security review
• performance tuning
• incident investigation
• full lifecycle / mixed work

4. Apply cloud guardrails before proposing changes. 5. Select the matching playbook and exact MCP command chain. 6. If local SDK-backed runtime checks are needed, use local-sdk-execution.md to choose live-port, hot-reload, or test mode. 7. Return evidence, risk, rollback, and any missing runtime prerequisites.

Normalize The Repo Layout

Use a dispatcher source root shaped like one of these public layouts:

Layout A: Standalone Dispatcher Package

<repo>/
  src/
    conf.d/
    conf.dispatcher.d/

Use config_path="<repo>/src" for sdk(...) actions.

Layout B: Dispatcher Subproject Inside A Larger Repo

<repo>/
  dispatcher/
    src/
      conf.d/
      conf.dispatcher.d/

Use config_path="<repo>/dispatcher/src" for sdk(...) actions.

If the user gives a broader repo root, resolve it to the dispatcher src directory before running validation or SDK checks.

Default Skill Routing

Default Command Chain

Use this minimum chain unless the selected playbook says otherwise:

1. Static structure:

• validate(...)
• lint(...)

2. Config integrity:

• sdk({"action":"check-files","config_path":"<dispatcher src path>"})
• sdk({"action":"diff-baseline","config_path":"<dispatcher src path>"}) when wrapper/include drift matters

3. Runtime evidence for behavior changes:

• trace_request(...)
• inspect_cache(...) when cache behavior changed
• tail_logs(...) and monitor_metrics(...) for incidents or performance analysis

Minimum Output

Always return:

• normalized dispatcher source root
• selected skill and playbook
• files or file families affected
• executed MCP commands and evidence
• selected test IDs from test-case-catalog.md
• rollback trigger and rollback action
• explicit note for any skipped runtime checks

Dispatcher Foundation References

This directory contains cross-cutting references shared by multiple dispatcher skills.

It is named dispatcher-foundation because these files support config authoring, incident response, performance tuning, security hardening, and technical advisory work. They are not advisory-only materials.

The specialist skills may also contain lightweight wrapper files that point back to this directory so local links remain predictable from each skill.

Repo Layout Workflows (Cloud Dispatcher)

Use this file to map a user request to the actual dispatcher repo layout before editing files or running MCP commands.

Here, "Dispatcher" refers to the Adobe Dispatcher Apache HTTP Server module and its HTTPD/dispatcher configuration files, not an AEM bundle.

Supported Public Layouts

Layout A: Standalone Dispatcher Package

<repo>/
  src/
    conf.d/
      available_vhosts/
      enabled_vhosts/
      rewrites/
    conf.dispatcher.d/
      available_farms/
      enabled_farms/
      filters/
      cache/
      clientheaders/
      renders/
      virtualhosts/

Dispatcher source root:

• <repo>/src

Layout B: Dispatcher Subproject Inside A Larger Repo

<repo>/
  dispatcher/
    src/
      conf.d/
      conf.dispatcher.d/

Dispatcher source root:

• <repo>/dispatcher/src

Workflow Maps

1) New Site Or New Public Domain

Primary playbook:

• config-authoring -> config-scenario-playbooks.md Playbook A or C

Usually touch:

• <src>/conf.d/available_vhosts/<site>.vhost
• <src>/conf.d/enabled_vhosts/<site>.vhost
• <src>/conf.d/rewrites/<site>_rewrites.rules
• <src>/conf.dispatcher.d/available_farms/<site>_farm.any
• <src>/conf.dispatcher.d/enabled_farms/<site>_farm.any
• <src>/conf.dispatcher.d/filters/<site>_filters.any
• <src>/conf.dispatcher.d/cache/<site>_cache.any

Runtime proof:

• canonical host redirect
• one allowed content URL
• one denied sensitive URL

2) Headless API, CORS, Or Persisted GraphQL

Primary playbook:

• config-authoring -> Playbook B, H, or I

Usually touch:

• <src>/conf.d/available_vhosts/<site>.vhost
• <src>/conf.d/rewrites/<site>_rewrites.rules
• <src>/conf.dispatcher.d/filters/<site>_filters.any
• <src>/conf.dispatcher.d/cache/<site>_cache.any
• <src>/conf.dispatcher.d/clientheaders/<site>_clientheaders.any

Runtime proof:

• preflight or API request trace
• persisted-query trace where applicable
• cache proof for one cacheable and one non-cacheable request

3) Security Hardening Or Release Gate

Primary playbook:

• security-hardening -> Playbook 1 or 3

Usually inspect first:

• <src>/conf.dispatcher.d/filters/*.any
• <src>/conf.dispatcher.d/cache/*.any
• <src>/conf.dispatcher.d/clientheaders/*.any
• <src>/conf.d/available_vhosts/*.vhost
• <src>/conf.d/rewrites/*.rules

Change only after evidence shows a gap.

4) Cache Or Invalidation Tuning

Primary playbook:

• performance-tuning -> Playbook 1, 2, 5, or 7

Usually touch:

• <src>/conf.dispatcher.d/cache/*.any
• <src>/conf.dispatcher.d/available_farms/*.any
• <src>/conf.d/available_vhosts/*.vhost

Runtime proof:

• cache object state
• hit/miss comparison
• invalidation scope rationale

5) Runtime Incident Triage

Primary playbook:

• incident-response -> Playbook 1, 2, 3, 4, 5, or 10

Inspect before editing:

• changed vhost, farm, filter, cache, and rewrite files under the dispatcher source root

Runtime proof:

• metrics window
• log evidence
• healthy vs failing request trace

6) Full Lifecycle Change

Primary playbook:

• workflow-orchestrator

Order: 1. normalize repo layout 2. pick the authoring playbook 3. run security and performance review for the touched surfaces 4. finish with release-gate validation and rollback notes

File-Family Heuristics

• Host and redirect changes usually start in conf.d/available_vhosts/ and conf.d/rewrites/.
• Farm behavior usually starts in conf.dispatcher.d/available_farms/.
• URL exposure rules usually start in conf.dispatcher.d/filters/.
• Cache policy usually starts in conf.dispatcher.d/cache/.
• Header forwarding usually starts in conf.dispatcher.d/clientheaders/.

Normalize to these file families before producing a change plan.

Dispatcher Test Case Catalog

Use these IDs when proposing or reporting verification scenarios.

Filter Coverage

Cache Coverage

Rewrite/Redirect Coverage

Header / Contract Coverage

Runtime Incident Coverage

Mode Compatibility Coverage

Minimum Selection Rule

For configuration changes, include at least:

• one filter test
• one cache test
• one rewrite/redirect test if rewrite logic changed
• one mode test for selected cloud mode

Capability Coverage Map (Cloud, Core-7)

This file maps dispatcher MCP capability requirements to the current skill + core-7 MCP execution model.

Tool Coverage Mapping

Prompt Intent Coverage

Prompt intent coverage is explicit across the dispatcher skills.

Resource Coverage Mapping

Execution Model

The dispatcher skills use a deterministic model:

1. fixed MCP runtime/validation primitives (core-7) 2. explicit skill workflows and output contracts 3. citation and rollback discipline

This keeps behavior auditable and open-source friendly.

Dispatcher Key Concepts (Advisory)

Use this reference when explaining Dispatcher behavior. Cite Experience League as the source of truth.

Filter Rules – Evaluation Order

When multiple filter patterns apply to a request, the last applied filter pattern is effective.

• Source: Dispatcher configuration – Content filter.
• Rule IDs (e.g. /0005, /0299) are labels only; they do not determine order. Order in the config file determines which rule is "last" for a given request.
• To deny a path that is already matched by a broader allow (e.g. /content/*), place the deny rule after that allow (e.g. at the end of the filter file or after the include that contains the allow).

URL Decomposition For Dispatcher Rules

Sling URL decomposition is the default request model across Dispatcher: filter rules, cache rules, and any other URL-based rules all reason about requests in terms of path, selectors, extension, and suffix. Use this decomposition whenever authoring or analyzing URL-based config.

Example URL: /content/wknd/us/en.page.print.a4.html/products/item?ref=nav

• resource path: /content/wknd/us/en
• selectors: page, print, a4
• extension: html
• suffix: /products/item
• query string: ref=nav (outside Dispatcher path matching)

Source: Dispatcher configuration – Content filter

Guidance:

• Filters: Use /path, /selectors, /extension, /suffix (not raw /url) for Sling-style URLs.
• Cache rules: Reason about what to cache using the same path/selectors/extension/suffix breakdown; globs or path patterns should align with this model.
• Match selectors/extension explicitly when behavior depends on render variant.
• Do not treat suffix as part of the resource path.
• When asked to "decompose a URL", return the five-part breakdown above before proposing rule changes.

Cache – statfileslevel

• `/statfileslevel` controls folder-level cache invalidation. Dispatcher creates .stat files in folders from docroot up to the configured level (docroot = 0).
• When content is invalidated (e.g. on publish), only .stat files along the path to the invalidated resource are touched; sibling branches are not invalidated.
• Higher statfileslevel = more granular invalidation = better cache persistence for unchanged content.
• Source: Invalidating files by folder level.

Cache – Invalidate vs Flush

• Auto-invalidate (e.g. on replication): Dispatcher touches .stat files; cached documents are refetched when requested if the .stat is newer than the cached file.
• Flush (explicit): Cache files are deleted (or a flush request is sent). Use for bulk or targeted flush from AEM.
• Source: Invalidating Dispatcher cache from AEM.

Cache – Freshness And Failure Controls

• `/serveStaleOnError` allows stale cache delivery when the backend is unavailable; it improves resilience but can hide origin instability if overused.
• `/gracePeriod` defines how long auto-invalidated stale resources may still be served during activation bursts.
• `/enableTTL` makes Dispatcher honor backend Cache-Control/Expires for cached resource expiry.
• `/allowAuthorized "0"` is the safe default for public publish traffic; do not enable authorized caching without a clear permission model and verification plan.

For cloud guidance, treat the current managed sample-farm values (serveStaleOnError=1, gracePeriod=2, enableTTL=1, allowAuthorized=0) as the baseline and justify any deviation explicitly.

HTTPD / Dispatcher Integration Defaults

• `DispatcherUseProcessedURL On` means rewrite processing affects what Dispatcher evaluates and forwards.
• `DispatcherPassError 0` keeps backend error handling behavior at the Dispatcher/AEM boundary unless deliberately changed.
• `DispatcherUseForwardedHost` controls whether X-Forwarded-Host influences host handling; treat host-forwarding behavior as a cloud trust-boundary setting.
• `DispatcherRestrictUncacheableContent On` strips cache headers added by mod_expires from content that should stay uncacheable.

When reviewing regressions in routing, redirects, or cache semantics, verify whether one of these integration settings explains the behavior before editing filters or cache rules.

Managed Default Includes Are Product Behavior, Not Noise

In AEMaaCS, the wrapper files (rewrite.rules, filters.any, rules.any, clientheaders.any, virtualhosts.any) extend managed defaults. Those defaults are not just examples; they encode supported cloud behavior.

Examples from the managed cloud baseline:

• default_clientheaders.any forwards auth/session/tracing headers needed by common AEM features
• default_filters.any allows supported endpoints for CSRF, GraphQL, persisted queries, Forms, and Screens
• default_rules.any denies caching on specific unsafe endpoints such as CSRF token responses
• default_rewrite.rules blocks common spoof/abuse patterns and rewrites persisted GraphQL requests for cache compatibility

Advice implication:

• do not remove or rewrite these includes casually
• when customizing, add the minimum delta around them and verify the supported feature path still behaves correctly

Header Forwarding And Upstream Contract

/clientheaders controls which request headers reach AEM. Removing a header can break authentication, tracing, host handling, or feature behavior without producing obvious syntax failures.

High-sensitivity forwarded headers in the cloud baseline include:

• Authorization
• Cookie
• Host
• X-Forwarded-Proto
• x-request-id

When a feature fails only after a clientheaders change, audit the header contract before changing filters or rewrites.

Persisted GraphQL Cache Rewrite

The managed default rewrite layer rewrites ^/graphql/execute.json requests with a ;.json suffix using [PT]. This is there so Dispatcher can cache persisted-query responses with a usable extension-backed cache file name.

Advice implication:

• if persisted-query caching or routing changes, verify this rewrite path still works
• treat persisted GraphQL behavior as the combination of filter rules, rewrite rules, cache settings, and CORS policy

Cloud Runtime Reserved And Environment-Sensitive Paths

• /systemready and /system/probes/* are cloud-runtime endpoints, not normal customer routes.
• /crx/(de|server)/ is intentionally proxied only in ENVIRONMENT_DEV.
• /content/test-site/ is intentionally proxied in ENVIRONMENT_DEV and ENVIRONMENT_STAGE.
• Commerce GraphQL, frontend-static, and Dynamic Media delivery paths have managed proxy/no-rewrite behavior in the base cloud vhost.

Advice implication:

• do not recommend blanket denies or redirects on these paths without considering environment and cloud-managed behavior
• distinguish customer-exposed routes from cloud-managed baseline routes

Security Posture

• Prefer deny-by-default: broad deny first, then explicit allows. Targeted denies for sensitive paths must appear after any matching allow (last match wins).
• Source: Security checklist.

AEMaaCS-Specific

• For Cloud, also consider: Caching in AEMaaCS, CDN, Traffic filter rules / WAF.

Core-7 Capability Playbook (Cloud)

Use this guide to achieve high-precision Dispatcher development/debugging outcomes with the current 7-tool MCP contract:

• validate
• lint
• sdk
• trace_request
• inspect_cache
• monitor_metrics
• tail_logs

This playbook captures high-value behavior previously spread across broader tool/prompt/resource surfaces and adapts it to the core execution contract.

For complete prompt/tool/resource coverage mapping, use capability-coverage-map.md.

Capability -> Core-7 Mapping

Development Playbooks

1) New Config / Major Refactor

1. Decompose representative URLs (path/selectors/extension/suffix). 2. Produce full merged sections for /filter, /cache, vhost/rewrite blocks. 3. validate({"config":"<merged dispatcher content>","type":"dispatcher"}); for Apache blocks also run validate({"config":"<vhost/rewrite block>","type":"httpd","config_type":"vhost"}). 4. lint({"mode":"config","target":"<merged dispatcher content>","analysis_depth":"deep"}) for filter-heavy edits. 5. sdk({"action":"check-files","config_path":"<dispatcher src path>"}); sdk({"action":"diff-baseline","config_path":"<dispatcher src path>"}) when drift matters. 6. Runtime checks on one allow, one deny, one cache candidate, plus reserved probe-path safety when rewrite/vhost behavior changes.

Deliver:

• file-level change intent
• final merged sections
• test IDs + outcomes
• risk/rollback

2) Filter Rule Authoring

1. Build deny-by-default baseline. 2. Add explicit business allows. 3. Add targeted sensitive denies after broad allows (last-match wins). 4. Verify selector/suffix-specific URLs and method constraints. 5. validate({"config":"<filter section content>","type":"dispatcher","config_type":"filter"}) + lint({"mode":"config","target":"<filter section content>","analysis_depth":"deep"}). 6. trace_request on allow/deny overlap URLs.

Deliver:

• final /filter section with stable ordering
• overlap proof where deny still wins

3) Rewrite and Redirect Changes

1. Validate Apache rewrite blocks with validate({"config":"<vhost/rewrite block>","type":"httpd","config_type":"vhost"}). 2. Validate dispatcher blocks separately with validate({"config":"<dispatcher.any section>","type":"dispatcher","config_type":"dispatcher.any"}). 3. Use trace_request to confirm canonical single-hop redirects, no loop, and no interference with /systemready or /system/probes/*. 4. Confirm query-string behavior and unmatched-host behavior explicitly.

Deliver:

• redirect-chain evidence
• loop-prevention evidence

4) Cache Strategy Changes

1. Validate /cache, invalidation, and related headers. 2. lint for cache-policy regressions. 3. inspect_cache for one cache-hit and one expected bypass. 4. monitor_metrics to verify no sustained hit-ratio regression.

Deliver:

• pre/post cache evidence
• invalidation scope rationale (statfileslevel)

5) Cloud Feature Proxy Paths

1. Determine whether the request belongs to a cloud-managed feature path: persisted GraphQL, Commerce proxy endpoint, frontend-static passthrough, Dynamic Media delivery, or environment-specific runtime path. 2. Preserve the managed no-rewrite/proxy block unless the user is intentionally changing that feature. 3. Validate vhost/httpd changes first, then run representative request traces. 4. Record whether behavior is expected in all environments or only in dev/stage.

Deliver:

• explicit environment assumptions
• proof that custom rules do not override the managed feature path

6) Client Header Forwarding / Host Contract

1. Identify which feature depends on the forwarded header set. 2. Keep default_clientheaders.any unless the change is intentionally replacing the managed baseline. 3. Review whether auth, cookie, host, protocol, or request-id headers are being removed. 4. Validate the farm config and trace one representative request for the affected feature.

Deliver:

• final /clientheaders block
• risk note for any removed high-sensitivity header

7) Pre-Deploy Gate

1. validate({"config":"<changed dispatcher.any content>","type":"dispatcher"}) -> optional validate({"config":"<changed vhost/rewrite content>","type":"httpd","config_type":"vhost"}) when Apache files changed -> lint({"mode":"directory","target":"<dispatcher src path>","strict_mode":true}) -> sdk({"action":"check-files","config_path":"<dispatcher src path>"}) -> sdk({"action":"diff-baseline","config_path":"<dispatcher src path>"}). 2. Run minimum runtime checks for changed behavior type. 3. Record skipped checks and required environment for completion.

Deliver:

• go/no-go with unresolved risks

Debugging Playbooks

8) Cache Miss Investigation

1. inspect_cache target URL. 2. trace_request to identify filter/cache stage behavior. 3. tail_logs for correlated request lines. 4. monitor_metrics for broader MISS trend. 5. Validate related config blocks (validate, lint).

9) 502/5xx Spike Investigation

1. monitor_metrics incident window and error trend. 2. tail_logs representative failures. 3. trace_request failing vs healthy URL. 4. inspect_cache for collateral cache impact. 5. validate({"config":"<suspect changed content>","type":"dispatcher"}) + lint({"mode":"directory","target":"<dispatcher src path>","strict_mode":true}) + sdk({"action":"check-files","config_path":"<dispatcher src path>"}) for recent config regressions.

10) URL Blocked / Unexpected 403

1. trace_request target URL and method. 2. Map URL decomposition to matching filter rules. 3. Prove whether block is intended by policy. 4. If change required, add minimal allow without weakening sensitive denies. 5. Re-run allow+deny overlap tests.

11) Probe Or Environment-Specific Path Regression

1. Check whether the failing path is a reserved probe path or an environment-sensitive route. 2. Confirm the active environment assumption before classifying it as a defect. 3. Use trace_request on the target path and a normal content URL to isolate whether the break is route-specific. 4. Re-run static validation on the vhost/rewrite scope before proposing a fix.

Source Discipline

• Use public-docs-index.md for source selection.
• Follow public-doc-citation-rules.md topic-to-citation minimums.
• Separate tool evidence from doc-based guidance.

Completion Criteria

A response is complete when it includes:

1. exact files/sections changed (or proposed) 2. executed checks and evidence 3. selected test IDs from test-case-catalog.md 4. clear rollback trigger + action 5. citations for non-trivial claims

Dispatcher Request Router

Use this router to select the primary dispatcher skill consistently.

Routing Rules

Intent Cues

Use simple cue words to route quickly:

• Config authoring cues: "add filter", "rewrite", "cache rule", "vhost change"
• Feature-path cues: "GraphQL persisted query", "Commerce", "frontend-static", "Dynamic Media", "auth_checker", "vanity", "clientheaders", "forwarded host", "x-forwarded-proto", "header forwarding"
• Filter: last matching rule wins; for targeted deny, add rule after broader allow.
• URL semantics cues: "selector", "selectors", "suffix", "extension", "URL decomposition"
• Incident cues: "spike", "outage", "stale", "403/404/5xx", "cache miss", "probe failed", "health check", "systemready"
• Migration cues: "migration", "dual mode", "compatibility", "cross-mode behavior"
• Performance cues: "optimize", "faster", "cache hit ratio", "load test", "capacity"
• Security cues: "audit", "harden", "security check", "penetration test", "compliance"
• Advisory cues: "why", "best practice", "what should we do", "doc reference"

Ambiguous Requests

If intent is mixed:

1. Start with technical-advisory to frame scope and assumptions. 2. Hand off to execution skill:

• config changes -> config-authoring
• live issue triage -> incident-response
• migration/dual-mode work -> technical-advisory with a mode delta checklist; compare against the matching technical-advisory skill in the other dispatcher variant when needed
• performance tuning/capacity work -> performance-tuning
• security hardening/audit work -> security-hardening
• environment-sensitive or cloud-runtime path question -> technical-advisory first, then config-authoring or incident-response

Handoff Payload

When handing off from advisory to an execution skill, include:

• selected mode (cloud)
• objective and acceptance criteria
• required test IDs from test-case-catalog.md
• required checks from mode-specific-verification-matrix.md
• key citations used to justify the approach

Completion Rule

A request is complete only when:

1. advisory content is source-backed (public-docs-index.md) 2. execution recommendations include MCP verification steps 3. risk and rollback expectations are explicit