@mthanh/vespercli 1.8.0 → 2.0.0

package/assets/copilot/packs/integrations/skills/gitlab-ci-skill/examples/python-click/.gitlab-ci.yml

@@ -0,0 +1,133 @@
+# GitLab CI for a Click-style Python project. Generated by the skill from a
+# fresh clone of pallets/click on 2026-05-22, with no .gitlab-ci.yml as input.
+#
+# Patterns to notice (the skill applies these by default; they're what makes the
+# YAML "idiomatic GitLab" rather than the lowest-common-denominator shape):
+#
+# - `.tox` hidden job with `extends:` reuse across 4 callers (lint, test,
+#   typing, docs). Beats copy-pasting `uv tool install tox --with tox-uv` four
+#   times.
+# - Schedule-gated full matrix: `test` runs Python 3.13 on every push; the full
+#   3.10-3.14 matrix lives on `test-matrix` and only fires when
+#   $CI_PIPELINE_SOURCE == "schedule". Keeps every-push pipelines fast, nightly
+#   schedules exercise the full grid.
+# - `needs: []` on every test-stage job so they start as soon as the pipeline
+#   begins, in parallel with `build`. The DAG (not stage order) drives execution.
+# - `workflow:rules:` blocks the duplicate branch + MR pipeline once an MR opens.
+# - Lockfile-keyed cache (`files: [uv.lock]`) keeps cache hits real.
+# - `deploy` is a stub gated to tags and default-branch, both manual. Honest
+#   about what it doesn't know yet; you wire the actual publish step.
+
+default:
+  image: ghcr.io/astral-sh/uv:python3.13-bookworm-slim
+  interruptible: true
+  cache:
+    key:
+      files: [uv.lock]
+    paths:
+      - .cache/uv/
+      - .tox/
+  before_script:
+    - export UV_CACHE_DIR=.cache/uv
+
+variables:
+  UV_LINK_MODE: copy
+  FORCE_COLOR: "1"
+  PY_COLORS: "1"
+
+# Skip duplicate branch + MR pipelines once an MR is open.
+workflow:
+  rules:
+    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
+    - if: $CI_COMMIT_BRANCH && $CI_OPEN_MERGE_REQUESTS
+      when: never
+    - if: $CI_COMMIT_BRANCH
+    - if: $CI_COMMIT_TAG
+
+stages:
+  - build
+  - test
+  - deploy
+
+# Reusable base for tox jobs: installs tox + tox-uv once, then runs the env.
+.tox:
+  before_script:
+    - export UV_CACHE_DIR=.cache/uv
+    - uv tool install tox --with tox-uv
+
+# Build wheel and sdist with uv (flit backend driven via PEP 517).
+build:
+  stage: build
+  script:
+    - uv build
+  artifacts:
+    paths: [dist/]
+    expire_in: 1 week
+
+lint:
+  stage: test
+  extends: .tox
+  script:
+    - uv tool run --from tox tox -e style
+  needs: []
+
+# Single Python version on every push. Scheduled pipelines exercise the full matrix (see test-matrix).
+test:
+  stage: test
+  extends: .tox
+  script:
+    - uv tool run --from tox tox -e py3.13 -- --junitxml=report.xml
+  artifacts:
+    reports:
+      junit: report.xml
+    when: always
+  needs: []
+
+# Fan out across supported Python versions. Runs on scheduled pipelines only.
+test-matrix:
+  stage: test
+  extends: .tox
+  image: ghcr.io/astral-sh/uv:python$PY_VERSION-bookworm-slim
+  script:
+    - uv tool run --from tox tox -e py$PY_VERSION -- --junitxml=report.xml
+  artifacts:
+    reports:
+      junit: report.xml
+    when: always
+  needs: []
+  parallel:
+    matrix:
+      - PY_VERSION: ["3.10", "3.11", "3.12", "3.13", "3.14"]
+  rules:
+    - if: $CI_PIPELINE_SOURCE == "schedule"
+
+typing:
+  stage: test
+  extends: .tox
+  script:
+    - uv tool run --from tox tox -e typing
+  needs: []
+
+docs:
+  stage: test
+  extends: .tox
+  script:
+    - uv tool run --from tox tox -e docs
+  artifacts:
+    paths: [docs/_build/dirhtml/]
+    expire_in: 1 week
+  needs: []
+
+# Stub. Replace with twine/uv publish to PyPI gated on $CI_COMMIT_TAG when ready.
+deploy:
+  stage: deploy
+  script:
+    - echo "Configure your deploy target. See https://docs.gitlab.com/ci/environments/"
+  needs: [build]
+  rules:
+    - if: $CI_COMMIT_TAG
+      when: manual
+      allow_failure: true
+    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
+      when: manual
+      allow_failure: true

package/assets/copilot/packs/integrations/skills/gitlab-ci-skill/examples/python-click/README.md

@@ -0,0 +1,31 @@
+# Example: Python + uv + tox (with `.tox` extends and schedule-gated matrix)
+
+**Source**: generated by the skill from a fresh clone of [`pallets/click`](https://github.com/pallets/click) on 2026-05-22, with no pre-existing `.gitlab-ci.yml`.
+
+Where `python-uv-tox/` shows the basic Python+uv shape, this one shows what happens when a project has a more elaborate tox configuration (style, type checking, docs in addition to tests).
+
+## Patterns this example demonstrates
+
+- **Hidden `.tox` job with `extends:` reuse across 4 callers** (lint, test, typing, docs). Beats copy-pasting `uv tool install tox --with tox-uv` four times.
+- **Schedule-gated full matrix**: `test` runs Python 3.13 on every push; the full 3.10-3.14 matrix lives on `test-matrix` and only fires when `$CI_PIPELINE_SOURCE == "schedule"`. Every-push pipelines stay fast; nightly schedules exercise the full grid.
+- **`workflow:rules:`** blocks the duplicate branch + MR pipeline once an MR opens (the classic gotcha for new GitLab users).
+- **`needs: []` on every test-stage job** so the DAG starts the test stage in parallel with build.
+- **Deploy stub** gated to both `$CI_COMMIT_TAG` and `$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH`, both manual.
+
+## YAML files
+
+- `.gitlab-ci.yml`: Workflow 1 (Create initial pipeline) capture.
+
+## Reproducing
+
+```bash
+git clone https://github.com/pallets/click /tmp/click
+cd /tmp/click
+rm -rf .gitlab-ci.yml .gitlab .github/workflows
+```
+
+Then in a fresh Claude Code (or other AI editor) session, prompt:
+
+> Set up GitLab CI for this repo.
+
+Compare the agent's output to the YAML in this directory. They should match in shape; small differences are expected (component versions, comments).

package/assets/copilot/packs/integrations/skills/gitlab-ci-skill/examples/python-uv-tox/.gitlab-ci.after-layered.yml

@@ -0,0 +1,59 @@
+# Workflow 2 demo: two skill invocations applied in sequence over .gitlab-ci.before.yml.
+#
+# Invocation 1: "Please add Secret Detection from the GitLab Catalog."
+#   Added: include of components/secret-detection at version 2.3.0.
+#
+# Invocation 2: "Could you also please improve the testing approach in this ci setup?"
+#   Rewrote the test job: parallel matrix on Python 3.9-3.13, venv-based install,
+#   pytest-cov with cobertura coverage report and JUnit results.
+#
+# Compare against .gitlab-ci.before.yml to see what each Workflow 2 invocation added.
+
+default:
+  image: ghcr.io/astral-sh/uv:python3.13-bookworm-slim
+  interruptible: true
+  cache:
+    key:
+      files: [uv.lock]
+    paths: [.cache/uv/]
+  before_script:
+    - export UV_CACHE_DIR=.cache/uv
+
+include:
+  - component: gitlab.com/components/secret-detection/secret-detection@2.3.0
+
+stages:
+  - build
+  - test
+
+# Build sdist + wheel (includes the C speedups extension)
+build:
+  stage: build
+  script:
+    - uv build
+  artifacts:
+    paths: [dist/]
+    expire_in: 1 week
+
+# Install the wheel into a clean venv, run pytest with coverage on every supported Python
+test:
+  stage: test
+  parallel:
+    matrix:
+      - PY: ["3.9", "3.10", "3.11", "3.12", "3.13"]
+  image: ghcr.io/astral-sh/uv:python${PY}-bookworm-slim
+  needs: []
+  script:
+    - uv venv
+    - source .venv/bin/activate
+    - uv pip install --no-deps .
+    - uv pip install pytest pytest-cov
+    - pytest --junitxml=report.xml --cov=markupsafe --cov-report=term --cov-report=xml:coverage.xml tests/
+  coverage: '/TOTAL.*?(\d+\.?\d*)%/'
+  artifacts:
+    reports:
+      junit: report.xml
+      coverage_report:
+        coverage_format: cobertura
+        path: coverage.xml
+    when: always

package/assets/copilot/packs/integrations/skills/gitlab-ci-skill/examples/python-uv-tox/.gitlab-ci.before.yml

@@ -0,0 +1,34 @@
+default:
+  image: ghcr.io/astral-sh/uv:python3.13-bookworm-slim
+  interruptible: true
+  cache:
+    key:
+      files: [uv.lock]
+    paths: [.cache/uv/]
+  before_script:
+    - export UV_CACHE_DIR=.cache/uv
+
+stages:
+  - build
+  - test
+
+# Build sdist + wheel (includes the C speedups extension)
+build:
+  stage: build
+  script:
+    - uv build
+  artifacts:
+    paths: [dist/]
+    expire_in: 1 week
+
+# Run pytest against the source tree
+test:
+  stage: test
+  script:
+    - uv sync --group tests
+    - uv run pytest --junitxml=report.xml
+  artifacts:
+    reports:
+      junit: report.xml
+    when: always
+  needs: []

package/assets/copilot/packs/integrations/skills/gitlab-ci-skill/examples/python-uv-tox/.gitlab-ci.broken.yml

@@ -0,0 +1,49 @@
+# Workflow 3 demo fixture: lint passes, but the pipeline fails at runtime.
+#
+# Intentional break: the image tag is misspelled (sllim instead of slim).
+# - glci lint passes (lint does not validate image existence).
+# - glci show passes (show does not pull images).
+# - glci run --simulate fails at image pull.
+# - glci run fails at image pull with the same error.
+#
+# Real GitLab logs would show:
+#   Error response from daemon: manifest for ghcr.io/astral-sh/uv:python3.13-bookworm-sllim not found
+#
+# The skill should diagnose this from the log alone, propose the one-character
+# fix (sllim -> slim), verify with show, and offer to confirm with `glci run
+# build --confirm-docker` if the user has Docker.
+
+default:
+  image: ghcr.io/astral-sh/uv:python3.13-bookworm-sllim
+  interruptible: true
+  cache:
+    key:
+      files: [uv.lock]
+    paths: [.cache/uv/]
+  before_script:
+    - export UV_CACHE_DIR=.cache/uv
+
+stages:
+  - build
+  - test
+
+# Build sdist + wheel (includes the C speedups extension)
+build:
+  stage: build
+  script:
+    - uv build
+  artifacts:
+    paths: [dist/]
+    expire_in: 1 week
+
+# Run pytest against the source tree
+test:
+  stage: test
+  script:
+    - uv sync --group tests
+    - uv run pytest --junitxml=report.xml
+  artifacts:
+    reports:
+      junit: report.xml
+    when: always
+  needs: []

package/assets/copilot/packs/integrations/skills/gitlab-ci-skill/examples/python-uv-tox/.gitlab-ci.optimized.yml

@@ -0,0 +1,65 @@
+# Workflow 4 demo: optimization of .gitlab-ci.after-layered.yml. One round, three changes.
+#
+# 1. Dropped Python 3.9 from the matrix.
+#    pyproject.toml declares requires-python = ">=3.10", so the 3.9 entry was
+#    either failing fast or building a stale resolution. One fewer job, no false
+#    signal.
+# 2. Added cache:key:prefix: "py${PY}" so each matrix entry gets its own cache
+#    slot. Previous shape had 5 jobs racing to write the same lockfile-keyed
+#    cache; last-writer-wins meant cross-version contention and cold caches.
+# 3. Moved `export UV_CACHE_DIR=.cache/uv` from before_script: into a top-level
+#    variables: block. variables: is visible to GitLab's cache: key resolver and
+#    cleans up before_script:; idiomatic GitLab pattern, no behavior change.
+#
+# Compare against .gitlab-ci.after-layered.yml to see the round 1 diff.
+
+default:
+  image: ghcr.io/astral-sh/uv:python3.13-bookworm-slim
+  interruptible: true
+  cache:
+    key:
+      prefix: "py${PY}"
+      files: [uv.lock]
+    paths: [.cache/uv/]
+
+variables:
+  UV_CACHE_DIR: .cache/uv
+
+include:
+  - component: gitlab.com/components/secret-detection/secret-detection@2.3.0
+
+stages:
+  - build
+  - test
+
+# Build sdist + wheel (includes the C speedups extension)
+build:
+  stage: build
+  script:
+    - uv build
+  artifacts:
+    paths: [dist/]
+    expire_in: 1 week
+
+# Install the wheel into a clean venv, run pytest with coverage on every supported Python
+test:
+  stage: test
+  parallel:
+    matrix:
+      - PY: ["3.10", "3.11", "3.12", "3.13"]
+  image: ghcr.io/astral-sh/uv:python${PY}-bookworm-slim
+  needs: []
+  script:
+    - uv venv
+    - source .venv/bin/activate
+    - uv pip install --no-deps .
+    - uv pip install pytest pytest-cov
+    - pytest --junitxml=report.xml --cov=markupsafe --cov-report=term --cov-report=xml:coverage.xml tests/
+  coverage: '/TOTAL.*?(\d+\.?\d*)%/'
+  artifacts:
+    reports:
+      junit: report.xml
+      coverage_report:
+        coverage_format: cobertura
+        path: coverage.xml
+    when: always

package/assets/copilot/packs/integrations/skills/gitlab-ci-skill/examples/python-uv-tox/.gitlab-ci.yml

@@ -0,0 +1,101 @@
+# MarkupSafe CI pipeline. Uses uv + tox-uv: tox installs the requested
+# Python interpreter via uv, so a single base image covers the full matrix.
+
+default:
+  image: ghcr.io/astral-sh/uv:python3.13-bookworm
+  interruptible: true
+  cache:
+    key:
+      files: [uv.lock]
+    paths:
+      - .cache/uv/
+      - .tox/
+  before_script:
+    - export UV_CACHE_DIR="$CI_PROJECT_DIR/.cache/uv"
+
+# Run MR pipelines when an MR is open, branch pipelines otherwise. Prevents
+# duplicate pipelines on push-to-branch-with-open-MR.
+workflow:
+  rules:
+    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
+    - if: $CI_COMMIT_BRANCH && $CI_OPEN_MERGE_REQUESTS
+      when: never
+    - if: $CI_COMMIT_BRANCH
+    - if: $CI_COMMIT_TAG
+
+stages:
+  - build
+  - test
+  - deploy
+
+# Shared base for tox jobs.
+.tox:
+  stage: test
+  needs: []
+  script:
+    - uvx --with tox-uv tox -e $TOX_ENV
+
+# pre-commit hooks (ruff, etc.)
+style:
+  stage: build
+  needs: []
+  script:
+    - uvx --with tox-uv tox -e style
+
+# Strict mypy check.
+typing:
+  stage: build
+  needs: []
+  script:
+    - uvx --with tox-uv tox -e typing
+
+# CPython matrix, including free-threaded builds.
+test:cpython:
+  extends: .tox
+  parallel:
+    matrix:
+      - TOX_ENV:
+          - py3.9
+          - py3.10
+          - py3.11
+          - py3.12
+          - py3.13
+          - py3.13t
+          - py3.14
+          - py3.14t
+
+# Free-threading stress test.
+test:parallel:
+  extends: .tox
+  variables:
+    TOX_ENV: parallel
+
+# PyPy compatibility.
+test:pypy:
+  extends: .tox
+  variables:
+    TOX_ENV: pypy3.11
+
+# Sphinx docs build with -W (warnings as errors).
+docs:
+  stage: test
+  needs: []
+  script:
+    - uvx --with tox-uv tox -e docs
+  artifacts:
+    paths: [docs/_build/dirhtml]
+    expire_in: 1 week
+
+# Build sdist + wheel. PyPI publishing not wired up; add a trusted-publisher
+# or twine job when ready (see docs.gitlab.com/ci/secrets/ for OIDC options).
+build:dist:
+  stage: deploy
+  needs: ["test:cpython", "test:pypy", "style", "typing"]
+  script:
+    - uv build
+  artifacts:
+    paths: [dist/]
+    expire_in: 1 month
+  rules:
+    - if: $CI_COMMIT_TAG
+    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

package/assets/copilot/packs/integrations/skills/gitlab-ci-skill/examples/python-uv-tox/README.md

@@ -0,0 +1,42 @@
+# Example: Python + uv + tox (full W1/W2/W3/W4 narrative)
+
+**Source**: generated by the skill from a fresh clone of [`pallets/markupsafe`](https://github.com/pallets/markupsafe) on 2026-05-22, with no pre-existing `.gitlab-ci.yml`.
+
+This is the most comprehensive example in the repo: five YAML files telling the complete story of how the skill behaves across all four of its workflows.
+
+## Patterns this example demonstrates
+
+- **`default:` block** for shared `image`, `interruptible`, `cache`, `before_script`.
+- **Lockfile-keyed cache**: `cache:key:files: [uv.lock]` so cache invalidates only when dependencies change.
+- **Build artifact** (sdist + wheel via `uv build`) flowing to downstream jobs.
+- **CI/CD Catalog component include**: `gitlab.com/components/secret-detection/secret-detection@2.3.0`, pinned to a release tag.
+- **Cross-version test matrix** with per-version cache slot via `cache:key:prefix: "py${PY}"` (optimized variant).
+- **`variables:` block** for `UV_CACHE_DIR` so the cache resolver sees it (idiomatic placement; cleaner than `before_script:`).
+
+## YAML files
+
+- `.gitlab-ci.yml`: Workflow 1 capture. The skill's straightforward output for this stack.
+- `.gitlab-ci.before.yml`: Workflow 2 starting state. Minimal pipeline ("just build + test, no matrix, no security").
+- `.gitlab-ci.after-layered.yml`: Workflow 2 result. Two skill invocations stacked: add Secret Detection from the Catalog, then improve testing (parallel matrix, pytest-cov, JUnit and cobertura reports).
+- `.gitlab-ci.broken.yml`: Workflow 3 starting state. Image tag typo (`sllim` instead of `slim`). Lint and show pass; only `glci run` catches it.
+- `.gitlab-ci.optimized.yml`: Workflow 4 result. Round-1 optimizations applied to `.after-layered.yml`: drop Python 3.9 (vs `requires-python = ">=3.10"`), per-PY cache prefix, `UV_CACHE_DIR` moved to `variables:`.
+
+## Reproducing
+
+```bash
+git clone https://github.com/pallets/markupsafe /tmp/markupsafe
+cd /tmp/markupsafe
+rm -rf .gitlab-ci.yml .gitlab .github/workflows
+```
+
+Then in a fresh Claude Code (or other AI editor) session, prompt:
+
+> Set up GitLab CI for this repo.
+
+For the W2/W3/W4 narratives, copy one of the other YAML files in as `.gitlab-ci.yml` first, then prompt accordingly:
+
+- W2: `Add Secret Detection from the GitLab CI Catalog to this pipeline.`
+- W3: paste the failing job log (the `sllim` image-pull error) and ask the skill to diagnose.
+- W4: `Can you optimize this pipeline?`
+
+Compare the agent's output to the YAML in this directory. They should match in shape; small differences are expected.

package/assets/copilot/packs/integrations/skills/gitlab-ci-skill/references/caching.md

@@ -0,0 +1,170 @@
+# Caching reference
+
+Load this when configuring `cache:` in a job or in `default:`. Cache reduces pipeline time by avoiding re-fetch and re-build of dependencies between pipelines.
+
+## Contents
+
+- What cache is, and what it is not
+- Cache key patterns (lock-file hash, per-branch, per-job, fallback keys)
+- Cache paths (per stack)
+- Cache policy (pull-push, pull, push)
+- Multiple caches per job
+- When cache is wrong
+- Cache and `default:`
+- Verifying cache hits
+
+## What cache is, and what it is not
+
+Cache is **for dependencies**: `node_modules/`, `.cargo/registry/`, `vendor/`, `.cache/pip/`. It is shared between pipelines on the same key.
+
+Artifacts are **for pipeline outputs**: build products, test reports, generated files. They flow between jobs in the same pipeline.
+
+Do not put pipeline outputs in cache. Do not put dependencies in artifacts.
+
+## Cache key patterns
+
+Use the right key for the right scope. Wrong key means stale cache (slow) or thrashing cache (no benefit).
+
+### Lock-file hash (recommended for most cases)
+
+```yaml
+cache:
+  key:
+    files:
+      - package-lock.json
+  paths:
+    - node_modules/
+```
+
+The key changes only when the lock file changes. Most jobs share the same cache across pipelines.
+
+Equivalents per stack:
+
+| Stack | Lock file |
+|---|---|
+| Node.js | `package-lock.json`, `yarn.lock`, `pnpm-lock.yaml` |
+| Python | `poetry.lock`, `Pipfile.lock`, `requirements.txt` (acceptable as a coarse key) |
+| Go | `go.sum` |
+| Ruby | `Gemfile.lock` |
+| Rust | `Cargo.lock` |
+
+### Per-branch
+
+```yaml
+cache:
+  key: $CI_COMMIT_REF_SLUG
+  paths: [node_modules/]
+```
+
+Each branch gets its own cache. Good when branches diverge in dependencies. Slow on first run of a new branch.
+
+### Per-job
+
+```yaml
+cache:
+  key: $CI_JOB_NAME-$CI_COMMIT_REF_SLUG
+  paths: [.cache/]
+```
+
+When different jobs in the same branch need disjoint cache. Rarely the right answer; prefer one cache shared via `default:cache:`.
+
+### Fallback keys
+
+```yaml
+cache:
+  key:
+    files: [package-lock.json]
+  fallback_keys:
+    - $CI_DEFAULT_BRANCH
+  paths: [node_modules/]
+```
+
+If the lock-file key has no cache, fall back to the default branch's cache. Reduces cold-start time on new branches.
+
+## Cache paths
+
+List directories explicitly. Globs work but are slower to resolve.
+
+| Stack | Cache paths |
+|---|---|
+| Node.js (npm) | `.npm/` (the registry cache; pair with `npm ci --cache .npm --prefer-offline`) |
+| Node.js (yarn) | `.yarn/cache/` |
+| Node.js (pnpm) | `.pnpm-store/` |
+| Python (pip) | `.cache/pip/` |
+| Python (poetry) | `.cache/pypoetry/` |
+| Go | `.go/pkg/mod/` (with `GOPATH=$CI_PROJECT_DIR/.go`) |
+| Ruby (bundler) | `vendor/ruby/` (with `bundle config set --local deployment true`) |
+| Rust (cargo) | `.cargo/registry/cache/`, `target/` (with `CARGO_HOME=$CI_PROJECT_DIR/.cargo`) |
+
+For environments where the home directory is not under `$CI_PROJECT_DIR`, set the tool-specific home variable so the cache lives inside the project directory (otherwise it is outside the cached path and lost between jobs).
+
+## Cache policy
+
+By default, jobs both pull and push the cache. Override when you want different behavior:
+
+- `policy: pull-push` (default): pull at start, push at end.
+- `policy: pull`: read-only. Use when the job consumes the cache but does not change it (test jobs that do not install dependencies).
+- `policy: push`: write-only. Use when the job populates the cache for downstream jobs (a dedicated "warm cache" job).
+
+```yaml
+.cache-base:
+  cache:
+    key:
+      files: [package-lock.json]
+    paths: [node_modules/]
+
+warm-cache:
+  extends: .cache-base
+  stage: .pre
+  cache:
+    policy: pull-push
+  script:
+    - npm ci
+
+test:
+  extends: .cache-base
+  cache:
+    policy: pull
+  script:
+    - npm test
+```
+
+## Multiple caches per job
+
+A job can declare a list of caches:
+
+```yaml
+test:
+  cache:
+    - key:
+        files: [package-lock.json]
+      paths: [.npm/]
+    - key: $CI_COMMIT_REF_SLUG-build
+      paths: [.cache/build-output/]
+```
+
+Use this when a job needs caches with different keys (e.g., one keyed on a lock file, another keyed per branch). Rare. Prefer one cache shared via `default:cache:` unless there is a concrete reason.
+
+## When cache is wrong
+
+- Build outputs that change every commit: use artifacts.
+- Anything secret: never put credentials in cache.
+- Large directories that change every run: cache costs upload + download every job; if the directory changes more than it stays the same, skip cache and accept the cold start.
+
+## Cache and `default:`
+
+If most jobs share one cache configuration, define it once in `default:`:
+
+```yaml
+default:
+  cache:
+    key:
+      files: [package-lock.json]
+    paths: [node_modules/, .npm/]
+```
+
+A job can still override `cache:` to declare its own configuration or `cache: []` to disable.
+
+## Verifying cache hits
+
+The job log shows whether cache was extracted: look for `Restoring cache` and `Successfully extracted cache`. If you see `Created cache <key>` followed by `Cache miss` on the next pipeline run, the key is changing unnecessarily; check that you are not hashing files that change every commit.