Surface cache controls in CLI and defaults #21

New issue

Open

opened 2025-11-19 13:21:17 +00:00 by glenux · 0 comments

glenux commented

2025-11-19 13:21:17 +00:00

Owner

title: Surface cache controls in CLI and defaults
description: Provide explicit CLI options/docs for cache usage and ensure sensible defaults, since users report cache never used (likely because enable_cache defaults to false and isn't exposed in CLI).
current_situation:

DocMachine::Build::Config sets enable_cache default true in code but CLI never exposes a flag to disable/enable; users cannot tell whether caching is active.
_pull_image logic effectively disables cache reuse (see task a95c1b2), but even with fixes we need explicit commands/flags to control behaviour.
Documentation/--help lacks information on caching directories, environment overrides, or how to refresh the cache.
expected_outcome:
CLI option (e.g., --cache/--no-cache) clearly toggles caching; help text documents XDG_CACHE_HOME usage.
Default behaviour ensures cache is used on subsequent runs without additional flags.
Docs/README updated with instructions and troubleshooting steps for cached images.
technical_details:
Add CLI flag(s) to DocMachine::Build::Cli and wire them to config.enable_cache or future cache policies.
Provide command (or option) to force refresh (skip cache) when needed.
Document caching in README/docs, including location and how to clean it.

--- title: Surface cache controls in CLI and defaults description: Provide explicit CLI options/docs for cache usage and ensure sensible defaults, since users report cache never used (likely because `enable_cache` defaults to false and isn't exposed in CLI). current_situation: - `DocMachine::Build::Config` sets `enable_cache` default true in code but CLI never exposes a flag to disable/enable; users cannot tell whether caching is active. - `_pull_image` logic effectively disables cache reuse (see task a95c1b2), but even with fixes we need explicit commands/flags to control behaviour. - Documentation/`--help` lacks information on caching directories, environment overrides, or how to refresh the cache. expected_outcome: - CLI option (e.g., `--cache/--no-cache`) clearly toggles caching; help text documents `XDG_CACHE_HOME` usage. - Default behaviour ensures cache is used on subsequent runs without additional flags. - Docs/README updated with instructions and troubleshooting steps for cached images. technical_details: - Add CLI flag(s) to `DocMachine::Build::Cli` and wire them to `config.enable_cache` or future cache policies. - Provide command (or option) to force refresh (skip cache) when needed. - Document caching in README/docs, including location and how to clean it. ---