Output Format

decoct always emits valid YAML. The output preserves the original document’s structure and key ordering — it is a strict subset of the input, not a reorganisation.

Compressed YAML

Values removed by compression passes are simply absent. There is no placeholder or tombstone. If removing a value leaves an empty mapping or sequence, prune-empty removes that container too.

# Input
services:
  web:
    image: nginx:1.25.3
    restart: "no"        # default — stripped
    privileged: false     # default — stripped
    ports:
      - "8080:80"

# Output (after strip-defaults with docker-compose schema)
services:
  web:
    image: nginx:1.25.3
    ports:
      - "8080:80"

Class Definitions

The emit-classes pass adds @class header comments listing every default that was stripped, grouped by path prefix. This allows an LLM to reconstruct full configuration from the compressed output.

# decoct: defaults stripped using docker-compose schema
# @class service-defaults: privileged=False, read_only=False, restart=no, stdin_open=False, tty=False
# @class service-healthcheck-defaults: interval=30s, retries=3, start_period=0s, timeout=30s
services:
  web:
    image: nginx:1.25.3
    restart: always
    ports:
      - "8080:80"

Here restart: always remains because it differs from the default listed in @class service-defaults. Long class lines are truncated to 100 characters with ....

Class naming

Classes derive from the path structure of stripped defaults:

Path pattern	Class name
`services.*.restart`	`service-defaults`
`services.*.healthcheck.interval`	`service-healthcheck-defaults`
Single top-level keys	`top-level-defaults`

Deviation Annotations

The annotate-deviations pass adds inline [!] comments to values that violate assertions:

Situation	Comment format
Value violates a pattern/value check	`# [!] standard: <expected value>`
Value violates a general assertion	`# [!] assertion: <assertion text>`
Required key is missing	Logged in pass report (no inline comment)

services:
  worker:
    image: acme-worker:latest  # [!] assertion: Image tags must be pinned
    logging:
      driver: syslog  # [!] standard: json-file

Deviation Summary

The deviation-summary pass adds a summary block at the top of the document:

# decoct: 2 deviations from standards
# [!] docker-no-latest: services.worker.image
# [!] docker-logging: services.worker.logging.driver
services:
  api:
    image: acme-api:3.1.0
  worker:
    image: acme-worker:latest  # [!] assertion: Image tags must be pinned

Secret Redaction

The strip-secrets pass replaces detected secrets with [REDACTED]:

services:
  db:
    environment:
      POSTGRES_PASSWORD: "[REDACTED]"
      DATABASE_URL: "[REDACTED]"

Secrets are detected by path patterns (*.password, *.api_key), regex patterns (AWS keys, GitHub tokens, PEM blocks), and Shannon entropy analysis.

Token Statistics

Printed to stderr with --stats or --stats-only:

Tokens: 342 -> 187 (saved 155, 45.3%)

Multi-file runs show per-file stats plus an aggregate total. Default encoding is cl100k_base (GPT-4, Claude).

Using Compressed Output with LLMs

Each output element serves a purpose for LLM consumers:

@class definitions — what defaults were stripped and how to reconstruct them
[!] annotations — which values need attention
Deviation summary — quick count and index of non-conformance

Suggested prompt preamble:

The following config has been compressed by decoct. Default values have been stripped — see @class definitions for reconstruction. Items marked [!] are deviations from standards.

Reconstituting Full Documents

To reconstruct from compressed output:

Read each @class line for stripped field=value pairs
For every node matching the class path pattern, add back each stripped pair not already present
Values in the compressed output take precedence — they differ from the default