🗃️ docs-cache

Deterministic local caching of external documentation for agents and developers

Purpose

Provides agents and developers with local access to external documentation without committing it to the repository.

Documentation is cached in a gitignored location, exposed to agent and tool targets via links or copies, and updated through sync commands or postinstall hooks.

Features

• Local only: Cache lives in the directory .docs (or a custom location) and can be gitignored.
• Deterministic: docs-lock.json pins commits and file metadata.
• Fast: Local cache avoids network roundtrips after sync.
• Flexible: Cache full repos or just the subdirectories you need.

Note: Sources are downloaded to a local cache. If you provide a targetDir, docs-cache creates a symlink or copy from the cache to that target directory.

Usage

# Initialize (optional)
npx docs-cache init

# Add source(s)
npx docs-cache add github:owner/repo#main

# Sync and lock
npx docs-cache sync
npx docs-cache sync --frozen

# Refresh tracked refs (write lock/materialized output)
npx docs-cache update <source-id>
npx docs-cache update --all --dry-run

# Optional: pin config ref(s) to commit SHA
npx docs-cache pin <source-id>

# Inspect / maintain
npx docs-cache verify
npx docs-cache status
npx docs-cache remove <source-id>
npx docs-cache clean

for more options: npx docs-cache --help

Recommended Workflow

Use this flow to keep behavior predictable (similar to package manager manifest + lock workflows):

1. Keep source intent in config (ref: "main", ref: "v1", or a commit SHA).
2. Run npx docs-cache update <id...> (or --all) to refresh selected sources and lock data.
3. Use npx docs-cache sync --frozen in CI to fail fast when lock data drifts.
4. Use npx docs-cache pin <id...> only when you explicitly want to rewrite config refs to commit SHAs.

Configuration

docs.config.json at project root (or a docs-cache field in package.json):

{
  "$schema": "https://github.com/fbosch/docs-cache/blob/master/docs.config.schema.json",
  "sources": [
    {
      "id": "framework",
      "repo": "https://github.com/framework/core.git",
      "ref": "main", // or specific commit hash
      "targetDir": "./agents/skills/framework-skill/references", // symlink/copy target
      "include": ["guide/**"], // file globs to include from the source
      "toc": true, // defaults to "compressed" (for agents)
    },
  ],
}

Options

Top-level

Field	Details	Required
cacheDir	Directory for cache. Default: .docs.	Optional
defaults	Default settings for all sources.	Optional
sources	List of repositories to sync.	Required

Show default and source options

Default options

These fields can be set in defaults and are inherited by every source unless overridden per-source.

Field	Details
ref	Branch, tag, or commit. Default: "HEAD".
mode	Cache mode. Default: "materialize".
include	Glob patterns to copy. Default: ["**/*.{md,mdx,markdown,mkd,txt,rst,adoc,asciidoc}"].
exclude	Glob patterns to skip. Default: [].
targetMode	How to link or copy from the cache to the destination. Default: "symlink" on Unix, "copy" on Windows.
required	Whether missing sources should fail. Default: true.
maxBytes	Maximum total bytes to materialize. Default: 200000000 (200 MB).
maxFiles	Maximum total files to materialize.
ignoreHidden	Skip hidden files and directories (dotfiles). Default: false.
allowHosts	Allowed Git hosts. Default: ["github.com", "gitlab.com", "visualstudio.com"].
toc	Generate per-source TOC.md. Default: true. Supports true, false, or a format: "tree" (human readable), "compressed"
unwrapSingleRootDir	If the materialized output is nested under a single directory, unwrap it (recursively). Default: true.

Brace expansion in include supports comma-separated lists (including multiple groups) like **/*.{md,mdx} and is capped at 500 expanded patterns per include entry. It does not support nested braces or numeric ranges.

Source options

Required

Field	Details
repo	Git URL.
id	Unique identifier for the source.

Optional (source-only)

Field	Details
targetDir	Path where files should be symlinked/copied to, outside .docs.

Note: Sources are always downloaded to .docs/<id>/. If you provide a targetDir; docs-cache will create a symlink or copy pointing from the cache to that target directory.

NPM Integration

Use postinstall to ensure documentation is available locally immediately after installation:

{
  "scripts": {
    "postinstall": "npx docs-cache sync --prune"
  }
}

License

MIT