Configuration Caching

Configuration — Caching

Two things in a PowerAutoDocs run are expensive: calling an AI provider, and launching a browser to render Mermaid diagrams into PNGs. Both are cached, in one folder.

cache:
  dir: .powerautodocs-cache      # default

Default	.powerautodocs-cache
Resolved relative to	the config file's directory — not your working directory
Contains	.powerautodocs-ai-cache.json and diagrams/

Resolving against the config directory means both caches land in the same place regardless of where the command happens to run from. With the recommended layout, that's PowerAutoDocs/.powerautodocs-cache/.

The two caches

	AI summary cache	Diagram cache
Location	<cache.dir>/.powerautodocs-ai-cache.json	<cache.dir>/diagrams/
Keyed on	a hash of the component's meaningful content	a hash of the Mermaid source text
Invalidated by	the component changing, or a prompt-version bump shipped in a new release	the diagram's source changing
Force refresh	--regenerate-ai	delete <cache.dir>/diagrams/

Both key on content, never on file timestamps or names. Renaming a file changes nothing; changing a flow's actions invalidates just that flow.

Orphaned AI entries (renamed or deleted components) are pruned automatically each run — but only within the component types enabled that run, so toggling a component off doesn't wipe its cached summaries.

A corrupt or unreadable cache file logs a warning and starts empty. It never fails a run.

Persisting the cache in ADO

This is the part that matters for cost. ADO pipeline agents are fresh VMs — nothing on disk survives between runs. Without intervention the cache starts empty every single execution, and every run pays full AI cost and re-renders every diagram, no matter how little changed.

The sample pipeline solves this by committing the cache folder back to the branch after each run (step 4):

git add -f PowerAutoDocs/.powerautodocs-cache/
git commit -m "chore: update powerautodocs cache [skip ci]"
git fetch origin "$(Build.SourceBranch)"
git rebase FETCH_HEAD
git push origin "HEAD:$(Build.SourceBranch)"

This requires:

• persistCredentials: true on the checkout step (step 0 in the sample)
• The ADO Build Service account having Contribute on the repo

Without the permission the push is rejected with TF401027: You need the Git 'GenericContribute' permission. The documentation itself is generated and published regardless — you lose caching, and cost. The step is continueOnError: true, so it logs a warning naming the permission rather than reddening a run whose documentation published fine.

Push to $(Build.SourceBranch), not $(Build.SourceBranchName). The latter is only the last path segment of the ref: on a branch named feature/docs it resolves to docs, and the cache is pushed to a new docs branch with no error at all. Both forms agree on main, so this stays invisible until someone runs the pipeline on a nested branch name. The fetch/rebase matters too — a long multi-solution run gives another commit time to land, which would otherwise make this push a rejected non-fast-forward.

Side effects worth knowing

• AI summaries land in pull requests. That's a feature: AI-written text gets reviewed before it's published, and summaries don't change unexpectedly between runs.
• Diagram PNGs are binary. Every run that changes a diagram adds a binary diff to the client repo's history. The two caches share one folder deliberately (one thing to commit, not two), so it's all-or-nothing: keep the commit-back step, or drop the git add -f line and accept no cross-run caching at all.

The cache folder holds real solution component names, AI-written summaries and rendered ER diagrams. It belongs in the client's repo. Treat it as client data.

Diagram cache gotcha

The diagram cache is keyed only on the Mermaid source text. Changes to render settings — resolution, background, viewport — invalidate nothing, because the source text didn't change. If a rendering change appears to have done nothing, delete <cache.dir>/diagrams/ and re-run.