@enjoys/context-engine 1.0.7 → 1.0.9

package/data/hover/dockerfile.json

@@ -3,143 +3,281 @@
   "hovers": {
     "FROM": {
       "contents": [
-        { "value": "```dockerfile\nFROM [--platform=<platform>] <image>[:<tag>|@<digest>] [AS <name>]\n```\nInitialize a new build stage and set the base image for subsequent instructions. A valid Dockerfile must start with a FROM instruction (ARG is the only instruction allowed before FROM). Multi-stage builds use multiple FROM instructions — each begins a new stage and resets the build context. Use `AS <name>` to name a stage for `COPY --from` references." }
+        {
+          "value": "```dockerfile\nFROM node:20-alpine AS builder\nFROM python:3.12-slim\nFROM --platform=linux/amd64 ubuntu:22.04\nFROM scratch\n```\n**FROM** initializes a new build stage and sets the base image. Every Dockerfile must begin with a `FROM` instruction (only `ARG` may precede it). Multiple `FROM` instructions create multi-stage builds. Use `AS name` to reference the stage later with `COPY --from=name`."
+        }
       ]
     },
     "RUN": {
       "contents": [
-        { "value": "```dockerfile\nRUN <command>                          # shell form\nRUN [\"executable\", \"param1\", \"param2\"] # exec form\n```\nExecute a command in a new layer on top of the current image and commit the result. The shell form runs via `/bin/sh -c` (or the `SHELL` override). The exec form (JSON array) runs the executable directly without shell processing. Each RUN instruction creates a new layer — combine commands with `&&` to reduce layers. BuildKit supports `--mount=type=cache|bind|secret|ssh|tmpfs` and `--network=default|none|host`." }
+        {
+          "value": "```dockerfile\n# Shell form\nRUN apt-get update && apt-get install -y curl\n\n# Exec form\nRUN [\"apt-get\", \"install\", \"-y\", \"curl\"]\n\n# BuildKit cache mount\nRUN --mount=type=cache,target=/var/cache/apt \\\n    apt-get update && apt-get install -y gcc\n\n# Heredoc\nRUN <<EOF\n#!/bin/bash\nset -e\napt-get update\napt-get install -y curl\nEOF\n```\n**RUN** executes a command in a new layer. Combine related commands with `&&` and clean up in the same `RUN` to reduce layer size. Use `--mount=type=cache` for package manager caches."
+        }
       ]
     },
     "CMD": {
       "contents": [
-        { "value": "```dockerfile\nCMD [\"executable\", \"param1\", \"param2\"]   # exec form (preferred)\nCMD [\"param1\", \"param2\"]                 # default params to ENTRYPOINT\nCMD command param1 param2                # shell form\n```\nProvide the default command for a running container. Only the **last** CMD in a Dockerfile takes effect. If the Dockerfile also has an ENTRYPOINT (exec form), CMD provides default arguments to it. CMD is overridden by any arguments passed to `docker run`." }
+        {
+          "value": "```dockerfile\n# Exec form (preferred)\nCMD [\"node\", \"server.js\"]\n\n# Shell form\nCMD node server.js\n\n# As ENTRYPOINT default params\nENTRYPOINT [\"python\"]\nCMD [\"app.py\"]\n```\n**CMD** sets the default command for the container. Only the last `CMD` takes effect. Exec form is preferred because it does not invoke a shell. When used with `ENTRYPOINT`, `CMD` provides default arguments."
+        }
+      ]
+    },
+    "ENTRYPOINT": {
+      "contents": [
+        {
+          "value": "```dockerfile\n# Exec form (preferred)\nENTRYPOINT [\"python\", \"-m\", \"flask\"]\n\n# With CMD defaults\nENTRYPOINT [\"python\"]\nCMD [\"app.py\"]\n\n# With tini for signal handling\nENTRYPOINT [\"tini\", \"--\"]\nCMD [\"node\", \"server.js\"]\n```\n**ENTRYPOINT** configures a container to run as an executable. Exec form is preferred. `CMD` arguments are appended. Override at runtime with `--entrypoint`. Use tini or dumb-init as PID 1 for proper signal handling."
+        }
       ]
     },
     "LABEL": {
       "contents": [
-        { "value": "```dockerfile\nLABEL <key>=<value> [<key>=<value> ...]\n```\nAdd metadata to an image as key-value pairs. Labels are inherited by child images. Use quotes for values with spaces. Combine labels in a single instruction to minimize layers. Standard OCI labels: `org.opencontainers.image.title`, `org.opencontainers.image.version`, `org.opencontainers.image.source`, `org.opencontainers.image.licenses`." }
+        {
+          "value": "```dockerfile\nLABEL maintainer=\"dev@example.com\"\nLABEL version=\"1.0\"\n\n# OCI annotations\nLABEL org.opencontainers.image.title=\"My App\" \\\n      org.opencontainers.image.version=\"1.0.0\" \\\n      org.opencontainers.image.authors=\"dev@example.com\"\n```\n**LABEL** adds metadata to the image. Use OCI annotation keys (`org.opencontainers.image.*`) for interoperability. View labels with `docker inspect`."
+        }
       ]
     },
     "MAINTAINER": {
       "contents": [
-        { "value": "```dockerfile\nMAINTAINER <name>\n```\n**Deprecated.** Sets the Author field of the generated image. Use `LABEL maintainer=\"name <email>\"` instead, which is more flexible and follows the label-based metadata convention." }
+        {
+          "value": "```dockerfile\n# Deprecated\nMAINTAINER dev@example.com\n\n# Use instead:\nLABEL org.opencontainers.image.authors=\"dev@example.com\"\n```\n**MAINTAINER** is deprecated. Use `LABEL org.opencontainers.image.authors` instead for setting the image author."
+        }
       ]
     },
     "EXPOSE": {
       "contents": [
-        { "value": "```dockerfile\nEXPOSE <port>[/<protocol>] [...]\n```\nDeclare that the container listens on the specified port(s) at runtime. The default protocol is TCP; append `/udp` for UDP. **EXPOSE does not publish the port** — it serves as documentation. Use `-p` flag in `docker run` or `ports:` in Docker Compose to actually publish ports to the host." }
+        {
+          "value": "```dockerfile\nEXPOSE 8080\nEXPOSE 80 443\nEXPOSE 53/udp\nEXPOSE 8080/tcp 8443/tcp\n```\n**EXPOSE** documents which ports the container listens on. It does not actually publish ports — use `-p` or `-P` flags at runtime. Protocol defaults to TCP if not specified."
+        }
       ]
     },
     "ENV": {
       "contents": [
-        { "value": "```dockerfile\nENV <key>=<value> [<key>=<value> ...]\n```\nSet environment variables that persist in both the build process and running containers. Variables set with ENV are available in subsequent Dockerfile instructions and at container runtime. Override at runtime with `docker run --env KEY=value`. For build-only variables, prefer `ARG`. Each ENV instruction creates a new layer." }
+        {
+          "value": "```dockerfile\nENV NODE_ENV=production\nENV APP_HOME=/app PATH=\"/app/bin:$PATH\"\n\n# Python best practice\nENV PYTHONDONTWRITEBYTECODE=1 \\\n    PYTHONUNBUFFERED=1\n```\n**ENV** sets environment variables that persist in the image and running containers. Values can be overridden with `docker run --env`. Use `ARG` for build-time-only variables to avoid leaking secrets."
+        }
       ]
     },
     "ADD": {
       "contents": [
-        { "value": "```dockerfile\nADD [--chown=<user>:<group>] [--chmod=<perms>] [--checksum=<hash>] <src> ... <dest>\n```\nCopy files, directories, or remote URLs into the image. Unlike COPY, ADD has two extra features: automatic tar archive extraction (gzip, bzip2, xz) and fetching from remote URLs. For simple file copies, **prefer COPY** — it is more transparent. `--chown` sets ownership (Linux only). `--checksum` validates remote URL content." }
+        {
+          "value": "```dockerfile\n# Local file\nADD app.tar.gz /opt/app\n\n# Remote URL\nADD https://example.com/file.txt /tmp/\n\n# With checksum verification\nADD --checksum=sha256:abc123... https://example.com/bin /usr/local/bin/\n```\n**ADD** copies files into the image. Unlike COPY, ADD supports remote URLs and auto-extracts tar archives. Prefer `COPY` for simple file operations. Use `ADD` when you need tar extraction or remote downloads."
+        }
       ]
     },
     "COPY": {
       "contents": [
-        { "value": "```dockerfile\nCOPY [--from=<name|index>] [--chown=<user>:<group>] [--chmod=<perms>] [--link] <src> ... <dest>\n```\nCopy files or directories from the build context into the image filesystem. Preferred over ADD for straightforward copies. `--from=<stage>` copies from a named build stage or external image. `--chown` sets file ownership (Linux only). `--link` creates an independent layer for better cache reuse and parallel extraction. Paths are relative to the build context." }
-      ]
-    },
-    "ENTRYPOINT": {
-      "contents": [
-        { "value": "```dockerfile\nENTRYPOINT [\"executable\", \"param1\", \"param2\"]  # exec form (preferred)\nENTRYPOINT command param1 param2               # shell form\n```\nConfigure the container to run as an executable. Arguments from `CMD` or `docker run` are appended after the exec-form ENTRYPOINT. Only the last ENTRYPOINT takes effect. The exec form is preferred because it receives Unix signals directly (important for graceful shutdown). The shell form wraps in `/bin/sh -c`, which does not forward signals to the child process." }
+        {
+          "value": "```dockerfile\nCOPY . /app\nCOPY --chown=1001:1001 . /app\nCOPY --chmod=755 entrypoint.sh /entrypoint.sh\nCOPY --from=builder /app/dist /usr/share/nginx/html\nCOPY --link package.json ./\n```\n**COPY** copies files from the build context into the image. Use `--from` to copy from another build stage (multi-stage). `--link` enables layer-independent copying for better cache reuse. Preferred over `ADD` for simple file copying."
+        }
       ]
     },
     "VOLUME": {
       "contents": [
-        { "value": "```dockerfile\nVOLUME [\"/path\"] | VOLUME /path1 /path2\n```\nCreate a mount point and mark it as holding externally mounted volumes. Data in a VOLUME persists beyond the container lifecycle. Any changes made to the volume directory **after** the VOLUME instruction during the build are discarded. Use named volumes or bind mounts at runtime for reliable persistence." }
+        {
+          "value": "```dockerfile\nVOLUME /data\nVOLUME [\"/data\", \"/logs\"]\n```\n**VOLUME** creates a mount point for externally mounted volumes. Data written to volumes persists independently of the container. Note: you cannot change volume contents during build after the VOLUME instruction."
+        }
       ]
     },
     "USER": {
       "contents": [
-        { "value": "```dockerfile\nUSER <user>[:<group>]\nUSER <UID>[:<GID>]\n```\nSet the user (and optionally group) for all subsequent `RUN`, `CMD`, and `ENTRYPOINT` instructions. The user must already exist in the image. Running as non-root is a **security best practice**. Override at runtime with `docker run --user`. Create users with `RUN adduser` or `RUN useradd` before the USER instruction." }
+        {
+          "value": "```dockerfile\n# By name\nUSER appuser\n\n# By UID:GID\nUSER 1001:1001\n\n# Best practice: create user first\nRUN groupadd -r appuser && useradd -r -g appuser appuser\nUSER appuser\n```\n**USER** sets the user for subsequent `RUN`, `CMD`, and `ENTRYPOINT` instructions. Always run production containers as non-root for security. Create the user with `RUN` before switching."
+        }
       ]
     },
     "WORKDIR": {
       "contents": [
-        { "value": "```dockerfile\nWORKDIR /path/to/workdir\n```\nSet the working directory for subsequent `RUN`, `CMD`, `ENTRYPOINT`, `COPY`, and `ADD` instructions. The directory is created automatically if it doesn't exist. Can be set multiple times; relative paths resolve against the previous WORKDIR. Use absolute paths for clarity. Environment variables (from `ENV`) can be used in the path." }
+        {
+          "value": "```dockerfile\nWORKDIR /app\nWORKDIR src\nWORKDIR /app/config\n```\n**WORKDIR** sets the working directory for `RUN`, `CMD`, `ENTRYPOINT`, `COPY`, and `ADD`. Creates the directory if it does not exist. Can be used multiple times; relative paths build on the previous `WORKDIR`. Prefer `WORKDIR` over `RUN cd`."
+        }
       ]
     },
     "ARG": {
       "contents": [
-        { "value": "```dockerfile\nARG <name>[=<default value>]\n```\nDefine a build-time variable passed via `docker build --build-arg <name>=<value>`. Unlike ENV, ARG values are **not** persisted in the final image or available at container runtime. ARG before FROM applies only to the FROM instruction. ARG after FROM is scoped to the current build stage. Predefined ARGs: `HTTP_PROXY`, `HTTPS_PROXY`, `FTP_PROXY`, `NO_PROXY`, `BUILDPLATFORM`, `TARGETPLATFORM`, `TARGETOS`, `TARGETARCH`." }
+        {
+          "value": "```dockerfile\n# With default\nARG VERSION=latest\nARG NODE_ENV=production\n\n# Before FROM (scoped to FROM)\nARG BASE_IMAGE=node:20-alpine\nFROM $BASE_IMAGE\n\n# Re-declare after FROM to use\nARG VERSION\nRUN echo $VERSION\n```\n**ARG** defines a build-time variable. Pass values with `--build-arg`. ARGs defined before `FROM` are only available in `FROM`. After `FROM`, re-declare to use in subsequent instructions. ARGs do not persist in the running container (use `ENV` for that)."
+        }
       ]
     },
     "ONBUILD": {
       "contents": [
-        { "value": "```dockerfile\nONBUILD <INSTRUCTION>\n```\nRegister a trigger instruction that executes when this image is used as the base for another build. The trigger fires right after the child's FROM instruction. Useful for creating reusable base images (e.g., `ONBUILD COPY . /app`, `ONBUILD RUN npm install`). `ONBUILD ONBUILD` is not permitted. Triggers are not inherited beyond one level." }
+        {
+          "value": "```dockerfile\nONBUILD COPY . /app\nONBUILD RUN npm install\n```\n**ONBUILD** registers a trigger instruction that fires when the image is used as a base. Useful for language-specific base images. The trigger runs before any instruction in the child Dockerfile."
+        }
       ]
     },
     "STOPSIGNAL": {
       "contents": [
-        { "value": "```dockerfile\nSTOPSIGNAL <signal>\n```\nSet the system call signal that will be sent to the container's PID 1 process to stop it. Accepts signal names (`SIGTERM`, `SIGKILL`, `SIGQUIT`, `SIGINT`) or unsigned numbers (e.g., `9`). Default is `SIGTERM`. Override at runtime with `docker run --stop-signal`. Ensure your application handles the chosen signal for graceful shutdown." }
+        {
+          "value": "```dockerfile\nSTOPSIGNAL SIGTERM\nSTOPSIGNAL SIGQUIT\nSTOPSIGNAL 9\n```\n**STOPSIGNAL** sets the signal sent to the container on `docker stop`. Default is SIGTERM. Use SIGQUIT for graceful shutdown with core dump, or SIGINT for applications expecting Ctrl+C."
+        }
       ]
     },
     "HEALTHCHECK": {
       "contents": [
-        { "value": "```dockerfile\nHEALTHCHECK [OPTIONS] CMD <command>\nHEALTHCHECK NONE\n```\nDefine how Docker tests whether the container is healthy. Options:\n- `--interval=DURATION` — time between checks (default 30s)\n- `--timeout=DURATION` — max time for a check to complete (default 30s)\n- `--start-period=DURATION` — grace period during startup (default 0s)\n- `--retries=N` — consecutive failures needed to mark unhealthy (default 3)\n\nThe command's exit code determines status: `0` = healthy, `1` = unhealthy. Only the last HEALTHCHECK takes effect. Use `HEALTHCHECK NONE` to disable a health check inherited from a base image." }
+        {
+          "value": "```dockerfile\nHEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \\\n    CMD curl -f http://localhost:8080/health || exit 1\n\n# Using wget (Alpine)\nHEALTHCHECK CMD wget --quiet --tries=1 --spider http://localhost:8080/ || exit 1\n\n# Disable inherited health check\nHEALTHCHECK NONE\n```\n**HEALTHCHECK** defines how Docker tests if a container is working. The command exit code indicates health: 0 = healthy, 1 = unhealthy. Only the last `HEALTHCHECK` takes effect. Use `NONE` to disable checks inherited from a base image."
+        }
       ]
     },
     "SHELL": {
       "contents": [
-        { "value": "```dockerfile\nSHELL [\"executable\", \"parameters\"]\n```\nOverride the default shell for the shell form of `RUN`, `CMD`, and `ENTRYPOINT`. The default on Linux is `[\"/bin/sh\", \"-c\"]`; on Windows it is `[\"cmd\", \"/S\", \"/C\"]`. SHELL can appear multiple times — each occurrence affects subsequent shell-form instructions. Common use cases: switching to bash (`SHELL [\"/bin/bash\", \"-c\"]`) or PowerShell on Windows." }
+        {
+          "value": "```dockerfile\n# Linux: switch to bash\nSHELL [\"/bin/bash\", \"-c\"]\n\n# Windows: switch to PowerShell\nSHELL [\"powershell\", \"-Command\"]\n```\n**SHELL** overrides the default shell for shell-form commands. Affects all subsequent `RUN`, `CMD`, and `ENTRYPOINT` instructions in shell form. Use to switch from sh to bash for better scripting features."
+        }
+      ]
+    },
+    "syntax": {
+      "contents": [
+        {
+          "value": "```dockerfile\n# syntax=docker/dockerfile:1\n# syntax=docker/dockerfile:1.7\n# syntax=docker/dockerfile:labs\n```\n**syntax** is a parser directive that sets the BuildKit frontend. Must be the very first line of the Dockerfile. Using `docker/dockerfile:1` ensures the latest stable Dockerfile syntax. The `labs` channel provides experimental features."
+        }
       ]
     },
-    "AS": {
+    "escape": {
       "contents": [
-        { "value": "```dockerfile\nFROM <image> AS <name>\n```\nName a build stage in a multi-stage build. The name can be referenced by `COPY --from=<name>` or `docker build --target=<name>`. Stage names are case-insensitive and must be unique within the Dockerfile. Naming stages makes Dockerfiles more readable and allows building specific stages with `--target`." }
+        {
+          "value": "```dockerfile\n# escape=\\\n# escape=`\n```\n**escape** is a parser directive that changes the escape character. Default is backslash (`\\`). On Windows, use backtick (`` ` ``) since backslash is a path separator. Must appear before any instruction or comment."
+        }
       ]
     },
-    "COPY --from": {
+    "--mount": {
       "contents": [
-        { "value": "```dockerfile\nCOPY --from=<name|index> <src> <dest>\n```\nCopy files from a named build stage (using `AS <name>`) or by stage index (0-based). Can also reference an external image: `COPY --from=nginx:alpine /etc/nginx/nginx.conf /etc/nginx/`. This is the core mechanism for multi-stage builds — build in one stage, copy artifacts to the final image." }
+        {
+          "value": "```dockerfile\n# Cache mount (package manager cache)\nRUN --mount=type=cache,target=/root/.cache/pip \\\n    pip install -r requirements.txt\n\n# Bind mount (read files without copying)\nRUN --mount=type=bind,source=config.json,target=/tmp/config.json \\\n    cat /tmp/config.json\n\n# Secret mount (never persisted)\nRUN --mount=type=secret,id=npmrc,target=/root/.npmrc \\\n    npm install\n\n# SSH mount\nRUN --mount=type=ssh git clone git@github.com:org/repo.git\n```\n**--mount** (BuildKit) attaches additional filesystems during `RUN`. Types: cache (persistent cache), bind (read context files), secret (sensitive data), ssh (agent forwarding), tmpfs (temp storage). Mounts are not committed to the image layer."
+        }
       ]
     },
-    "--mount=type=cache": {
+    "--link": {
       "contents": [
-        { "value": "```dockerfile\nRUN --mount=type=cache,target=<path>[,id=<id>][,sharing=<shared|private|locked>] <command>\n```\nMount a persistent cache directory that survives across builds. Ideal for package manager caches:\n- APT: `--mount=type=cache,target=/var/cache/apt`\n- pip: `--mount=type=cache,target=/root/.cache/pip`\n- Go: `--mount=type=cache,target=/root/.cache/go-build`\n- npm: `--mount=type=cache,target=/root/.npm`\n\nRequires BuildKit (`DOCKER_BUILDKIT=1`)." }
+        {
+          "value": "```dockerfile\nCOPY --link package.json ./\nCOPY --link --from=builder /app/dist ./dist\n```\n**--link** flag for `COPY`/`ADD` creates a layer independent of previous layers. When the base image changes, linked layers can be reused without rebuilding. Significantly improves cache hit rates in multi-stage builds."
+        }
       ]
     },
-    "--mount=type=secret": {
+    "--checksum": {
       "contents": [
-        { "value": "```dockerfile\nRUN --mount=type=secret,id=<id>[,target=<path>][,required=<bool>][,mode=<mode>][,uid=<uid>][,gid=<gid>] <command>\n```\nMount a secret file that is available during the build step but **not** stored in the final image or any layer. Build with: `docker build --secret id=mysecret,src=secret.txt .`. The secret is available at `/run/secrets/<id>` by default. Use for API keys, credentials, and private SSH keys." }
+        {
+          "value": "```dockerfile\nADD --checksum=sha256:24454f830cdb571e2c4ad15481119c43b3cafd48dd869a9b2015d0c... \\\n    https://example.com/binary /usr/local/bin/\n```\n**--checksum** verifies the SHA256 hash of a remote file added with `ADD`. Ensures the downloaded file has not been tampered with. Only supported with URL sources."
+        }
       ]
     },
-    "--mount=type=ssh": {
+    "--chmod": {
       "contents": [
-        { "value": "```dockerfile\nRUN --mount=type=ssh <command>\n```\nForward the host's SSH agent socket into the build container, allowing access to private Git repositories without embedding SSH keys in the image. Build with: `docker build --ssh default .`. Requires BuildKit." }
+        {
+          "value": "```dockerfile\nCOPY --chmod=755 entrypoint.sh /entrypoint.sh\nCOPY --chmod=644 config.yaml /etc/app/\nADD --chmod=755 https://example.com/binary /usr/local/bin/\n```\n**--chmod** sets file permissions on `COPY`/`ADD` operations. Uses octal notation. Avoids needing a separate `RUN chmod` layer, which saves space and build time."
+        }
+      ]
+    },
+    "--chown": {
+      "contents": [
+        {
+          "value": "```dockerfile\nCOPY --chown=node:node package.json ./\nCOPY --chown=1001:1001 . /app\nADD --chown=www-data:www-data files/ /var/www/\n```\n**--chown** sets ownership on `COPY`/`ADD` operations. Accepts user/group names or UID/GID numbers. Avoids a separate `RUN chown` layer. Names are resolved from the image `/etc/passwd` and `/etc/group`."
+        }
       ]
     },
     "--platform": {
       "contents": [
-        { "value": "```dockerfile\nFROM --platform=<platform> <image>\n```\nSpecify the platform for the base image in multi-platform builds. Common values: `linux/amd64`, `linux/arm64`, `linux/arm/v7`. Use `$BUILDPLATFORM` for the build machine's platform and `$TARGETPLATFORM` for the target. Enables cross-compilation patterns in multi-stage builds." }
+        {
+          "value": "```dockerfile\nFROM --platform=linux/amd64 node:20-alpine\nFROM --platform=$BUILDPLATFORM golang:1.22 AS builder\nFROM --platform=$TARGETPLATFORM debian:bookworm-slim\n```\n**--platform** in `FROM` sets the target platform for that build stage. Use `$BUILDPLATFORM` for stages that run native tools (compilers). Use `$TARGETPLATFORM` or explicit values for the final image. Essential for cross-compilation workflows."
+        }
+      ]
+    },
+    "--network": {
+      "contents": [
+        {
+          "value": "```dockerfile\nRUN --network=none pip install --no-deps -r requirements.txt\nRUN --network=host curl http://host-service:8080/\n```\n**--network** controls network access during `RUN`. `none` disables all networking (security hardening). `host` uses the host network stack. Default provides normal container networking."
+        }
+      ]
+    },
+    "--security": {
+      "contents": [
+        {
+          "value": "```dockerfile\nRUN --security=insecure apt-get install -y privileged-package\n```\n**--security=insecure** runs the command with elevated privileges. Requires the `security.insecure` entitlement to be enabled. Use sparingly and only when absolutely necessary."
+        }
+      ]
+    },
+    "build stage": {
+      "contents": [
+        {
+          "value": "```dockerfile\nFROM node:20-alpine AS deps\nRUN npm ci\n\nFROM node:20-alpine AS builder\nCOPY --from=deps /app/node_modules ./node_modules\nRUN npm run build\n\nFROM nginx:alpine\nCOPY --from=builder /app/dist /usr/share/nginx/html\n```\n**Build stages** are created by each `FROM` instruction. Name them with `AS` and reference with `COPY --from`. Each stage starts fresh. Only the last stage (or `--target` stage) produces the final image."
+        }
       ]
     },
     "multi-stage build": {
       "contents": [
-        { "value": "**Multi-stage builds** use multiple `FROM` instructions in a single Dockerfile. Each FROM begins a new stage. Stages can be named with `AS <name>`. Use `COPY --from=<name>` to copy build artifacts from one stage to another.\n\nBenefits:\n- Dramatically smaller final images (no build tools in production)\n- Single Dockerfile for build and runtime\n- Parallel stage execution with BuildKit\n- Selective stage building with `--target`\n\n```dockerfile\nFROM golang:1.22 AS builder\nRUN go build -o /app\n\nFROM alpine:3.19\nCOPY --from=builder /app /app\n```" }
+        {
+          "value": "```dockerfile\n# Build stage: has all tools\nFROM golang:1.22 AS builder\nCOPY . .\nRUN go build -o /app\n\n# Final stage: minimal\nFROM gcr.io/distroless/static-debian12\nCOPY --from=builder /app /app\nENTRYPOINT [\"/app\"]\n```\n**Multi-stage builds** use multiple `FROM` statements. Build stages contain compilers and tools; the final stage contains only the application. This can reduce image size by 90%+. Use `--target` to build a specific stage."
+        }
+      ]
+    },
+    "build cache": {
+      "contents": [
+        {
+          "value": "```dockerfile\n# Good: dependencies first (cached), source second\nCOPY package.json package-lock.json ./\nRUN npm ci\nCOPY . .\n\n# Bad: any source change invalidates npm ci cache\nCOPY . .\nRUN npm ci\n```\n**Build cache** reuses layers when instructions and their inputs are unchanged. Order instructions from least to most frequently changing. Mount caches for package managers with `--mount=type=cache`. Use `.dockerignore` to exclude files that cause unnecessary cache invalidation."
+        }
       ]
     },
-    ".dockerignore": {
+    "build context": {
       "contents": [
-        { "value": "**`.dockerignore`** excludes files from the build context sent to the Docker daemon. Follows `.gitignore` syntax. Place it in the build context root.\n\n```\nnode_modules\n.git\n.env\n*.md\nDockerfile\n.dockerignore\ndist\ncoverage\n__pycache__\n*.pyc\n.venv\n```\n\nReduces build context size, speeds up builds, and prevents sensitive files from being included in images." }
+        {
+          "value": "```dockerfile\n# .dockerignore\nnode_modules\n.git\n*.md\nDockerfile\n```\n**Build context** is the set of files sent to the Docker daemon. Defined by the path in `docker build <path>`. Use `.dockerignore` to exclude large or sensitive files. A smaller context means faster builds. The build context is the root for `COPY` and `ADD` source paths."
+        }
       ]
     },
-    "BuildKit": {
+    "layer": {
       "contents": [
-        { "value": "**BuildKit** is Docker's next-generation build engine (default since Docker 23.0). Enable with `DOCKER_BUILDKIT=1` for older versions.\n\nFeatures:\n- Parallel stage execution in multi-stage builds\n- `RUN --mount` (cache, secret, ssh, bind, tmpfs)\n- `COPY --link` for independent layers\n- Better caching and faster builds\n- Build secrets that don't leak into image layers\n- Syntax directives: `# syntax=docker/dockerfile:1`" }
+        {
+          "value": "```dockerfile\n# Each instruction creates a layer:\nFROM ubuntu:22.04          # Layer 1: base\nRUN apt-get update         # Layer 2: package index\nCOPY . /app                # Layer 3: app files\nRUN npm install            # Layer 4: dependencies\n\n# Combine to reduce layers:\nRUN apt-get update && apt-get install -y curl \\\n    && rm -rf /var/lib/apt/lists/*\n```\n**Layers** are filesystem diffs stacked to form an image. Each `RUN`, `COPY`, and `ADD` creates a layer. Layers are cached and shared. Minimize layer count by combining related commands. Clean up temporary files in the same layer to reduce size."
+        }
       ]
     },
-    "scratch": {
+    "BUILDPLATFORM": {
       "contents": [
-        { "value": "```dockerfile\nFROM scratch\n```\n`scratch` is an explicitly empty image — the most minimal base image possible. Contains no files, no shell, no libraries. Use for:\n- Statically compiled Go binaries (`CGO_ENABLED=0`)\n- Statically linked Rust binaries\n- Minimal containers with single-binary applications\n\nYou must COPY everything the binary needs, including CA certificates if making HTTPS requests:\n```dockerfile\nCOPY --from=builder /etc/ssl/certs/ca-certificates.crt /etc/ssl/certs/\n```" }
+        {
+          "value": "```dockerfile\nFROM --platform=$BUILDPLATFORM golang:1.22 AS builder\nARG TARGETPLATFORM\nARG TARGETOS\nARG TARGETARCH\nRUN GOOS=$TARGETOS GOARCH=$TARGETARCH go build -o /app\n```\n**BUILDPLATFORM** is an automatic build arg containing the platform of the node performing the build (e.g., `linux/amd64`). Use it with `FROM --platform=$BUILDPLATFORM` to run build tools natively, then cross-compile for the target platform."
+        }
       ]
-    }
+    },
+    "TARGETPLATFORM": {
+      "contents": [
+        {
+          "value": "```dockerfile\nFROM --platform=$TARGETPLATFORM debian:bookworm-slim\nARG TARGETPLATFORM\nRUN echo \"Building for $TARGETPLATFORM\"\n```\n**TARGETPLATFORM** is the target platform specified by `--platform` (e.g., `linux/arm64`). Automatically set by BuildKit. Use it to download platform-specific binaries or configure builds."
+        }
+      ]
+    },
+    "TARGETOS": {
+      "contents": [
+        {
+          "value": "```dockerfile\nARG TARGETOS\nARG TARGETARCH\nRUN GOOS=$TARGETOS GOARCH=$TARGETARCH go build -o /app\n```\n**TARGETOS** contains the OS component of the target platform (e.g., `linux`, `windows`). Used for cross-compilation, especially with Go."
+        }
+      ]
+    },
+    "TARGETARCH": {
+      "contents": [
+        {
+          "value": "```dockerfile\nARG TARGETARCH\nRUN curl -L https://example.com/binary-${TARGETARCH} -o /usr/local/bin/binary\n```\n**TARGETARCH** contains the architecture component (e.g., `amd64`, `arm64`, `arm`). Use to download or build platform-specific binaries."
+        }
+      ]
+    },
+    "TARGETVARIANT": {
+      "contents": [
+        {
+          "value": "```dockerfile\nARG TARGETARCH\nARG TARGETVARIANT\nRUN echo \"arch=$TARGETARCH variant=$TARGETVARIANT\"\n```\n**TARGETVARIANT** contains the variant component (e.g., `v7` for `arm/v7`). Useful for ARM variant-specific builds."
+        }
+      ]
+    },
+    "--mount=type=bind": "## --mount=type=bind\n\n```dockerfile\nRUN --mount=type=bind,source=<src>,target=<dest>[,from=<stage>] <command>\n```\n\nBind mount a directory from the build context or another stage.\n\n```dockerfile\n# Mount source code read-only\nRUN --mount=type=bind,target=/src go build -o /app /src/cmd/server\n\n# Mount from another stage\nFROM build AS deps\nRUN --mount=type=bind,from=deps,source=/go/pkg,target=/go/pkg go build\n```\n\n**Key options:**\n- `source` — path in context/stage (default: root)\n- `target` — mount point in container\n- `from` — source stage name\n- `rw` — read-write (default: read-only)",
+    "--mount=type=cache": "## --mount=type=cache\n\n```dockerfile\nRUN --mount=type=cache,target=<path>[,id=<id>][,sharing=shared] <command>\n```\n\nPersistent cache directory across builds. Dramatically speeds up package installs.\n\n```dockerfile\n# Go module cache\nRUN --mount=type=cache,target=/go/pkg/mod \\\n    go build -o /app .\n\n# npm cache\nRUN --mount=type=cache,target=/root/.npm \\\n    npm ci\n\n# pip cache\nRUN --mount=type=cache,target=/root/.cache/pip \\\n    pip install -r requirements.txt\n\n# apt cache\nRUN --mount=type=cache,target=/var/cache/apt \\\n    --mount=type=cache,target=/var/lib/apt \\\n    apt-get update && apt-get install -y curl\n```\n\n**Options:**\n- `id` — unique cache ID (default: target path)\n- `sharing` — `shared` (default), `private`, `locked`",
+    "--mount=type=secret": "## --mount=type=secret\n\n```dockerfile\nRUN --mount=type=secret,id=<id>[,target=<path>] <command>\n```\n\nMount a secret file without baking it into the image layer.\n\n```dockerfile\n# Access secret during build\nRUN --mount=type=secret,id=npmrc,target=/root/.npmrc \\\n    npm ci\n\nRUN --mount=type=secret,id=aws,target=/root/.aws/credentials \\\n    aws s3 cp s3://bucket/file .\n```\n\n**Pass secret at build time:**\n```bash\ndocker build --secret id=npmrc,src=$HOME/.npmrc .\ndocker build --secret id=aws,src=$HOME/.aws/credentials .\n```\n\n**Note:** Secret is never saved in image layers.",
+    "--mount=type=ssh": "## --mount=type=ssh\n\n```dockerfile\nRUN --mount=type=ssh <command>\n```\n\nForward SSH agent to access private repos during build.\n\n```dockerfile\nRUN --mount=type=ssh \\\n    git clone git@github.com:private/repo.git /app\n\nRUN --mount=type=ssh \\\n    pip install git+ssh://git@github.com/private/package.git\n```\n\n**Build with SSH:**\n```bash\ndocker build --ssh default .\n# or specific key:\ndocker build --ssh default=$HOME/.ssh/id_rsa .\n```\n\n**Prerequisite:** `ssh-add` your key before building.",
+    "--mount=type=tmpfs": "## --mount=type=tmpfs\n\n```dockerfile\nRUN --mount=type=tmpfs,target=<path>[,size=<bytes>] <command>\n```\n\nMount a tmpfs (RAM-backed) filesystem.\n\n```dockerfile\nRUN --mount=type=tmpfs,target=/tmp \\\n    compile-something --temp-dir=/tmp\n```\n\nUseful for build steps that need fast temporary storage.",
+    "BUILDARCH": "## BUILDARCH\n\n```dockerfile\nARG BUILDARCH\n```\n\nAutomatic build argument containing the CPU architecture of the build machine.\n\n**Values:** `amd64`, `arm64`, `arm`, `386`, `ppc64le`, `s390x`\n\n```dockerfile\nFROM golang:1.22\nARG BUILDARCH\nRUN echo \"Building on: $BUILDARCH\"\n```\n\n**Related:** `BUILDOS`, `BUILDPLATFORM`, `BUILDVARIANT`",
+    "BUILDOS": "## BUILDOS\n\n```dockerfile\nARG BUILDOS\n```\n\nAutomatic build argument containing the OS of the build machine.\n\n**Values:** `linux`, `windows`, `darwin`\n\n```dockerfile\nARG BUILDOS\nRUN echo \"Build OS: $BUILDOS\"\n```",
+    "BUILDVARIANT": "## BUILDVARIANT\n\n```dockerfile\nARG BUILDVARIANT\n```\n\nAutomatic build argument for the CPU variant (e.g., `v7` for ARMv7).\n\n```dockerfile\nARG BUILDVARIANT\nRUN echo \"Variant: ${BUILDVARIANT:-none}\"\n```",
+    ".dockerignore": "## .dockerignore\n\nFile that controls what gets sent to the Docker daemon as build context.\n\n```\n# .dockerignore\n.git\n.gitignore\nnode_modules\nnpm-debug.log\nDockerfile*\ndocker-compose*\n.dockerignore\n.env\n*.md\n.vscode\n__pycache__\n*.pyc\ndist\nbuild\n.tox\ncoverage\n.nyc_output\n```\n\n**Pattern syntax:**\n- `*` matches any sequence (excluding path separators)\n- `**` matches any number of directories\n- `!` excludes from ignore (re-include)\n- `#` comment line\n\n**Example with exception:**\n```\n*.md\n!README.md\n```\n\n**Why it matters:** Large build contexts slow down builds. Always exclude `node_modules`, `.git`, etc.",
+    "heredoc": "## Heredoc Syntax\n\nInline multi-line content in Dockerfile (BuildKit 1.4+).\n\n**Inline files:**\n```dockerfile\n# syntax=docker/dockerfile:1\nCOPY <<EOF /app/config.json\n{\"port\": 3000}\nEOF\n```\n\n**Multi-line RUN:**\n```dockerfile\nRUN <<EOF\napt-get update\napt-get install -y curl git\nrm -rf /var/lib/apt/lists/*\nEOF\n```\n\n**With interpreter:**\n```dockerfile\nRUN <<EOF python3\nimport os\nprint(os.environ)\nEOF\n```\n\n**Multiple files:**\n```dockerfile\nCOPY <<app.py <<requirements.txt /app/\nfrom flask import Flask\napp = Flask(__name__)\napp.py\nflask>=3.0\nrequirements.txt\n```\n\n**Requires:** `# syntax=docker/dockerfile:1` or BuildKit >= 0.10",
+    "--parents": "## --parents (COPY flag)\n\n```dockerfile\nCOPY --parents <src> <dest>\n```\n\nPreserve the parent directory structure when copying.\n\n```dockerfile\n# Without --parents:\nCOPY src/app/config.json /dest/\n# Result: /dest/config.json\n\n# With --parents:\nCOPY --parents src/app/config.json /dest/\n# Result: /dest/src/app/config.json\n```\n\n**Requires:** BuildKit",
+    "--keep-git-dir": "## --keep-git-dir\n\n```dockerfile\nADD --keep-git-dir=true <git-url> <dest>\n```\n\nKeep the .git directory when adding from a Git repository URL.\n\n```dockerfile\nADD --keep-git-dir=true https://github.com/user/repo.git#main /src\n```\n\nBy default, .git is stripped. Useful when build needs Git metadata (version, commit hash)."
   }
-}
+}