🗃️ 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. When enabled, docs-cache exposes sources to OpenCode as local references. Optional links or copies remain available for other tools.

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.
• OpenCode-aware: Detected OpenCode configs can expose every source as an @ reference.

Note: Sources always materialize in the local cache. targetDir is optional and only creates a symlink or copy for tools that need a separate physical path.

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 install
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

Requirements

• Node.js 24 or later

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 install to restore cache/targets from docs-lock.json without rewriting the lock file.
4. Use npx docs-cache sync --frozen in CI to fail fast when lock data or managed OpenCode references drift.
5. 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
       "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
opencode	OpenCode reference-sync decision.	Optional
sources	List of repositories to sync.	Required

OpenCode references

docs-cache init and interactive docs-cache sync detect project-local opencode.json and opencode.jsonc files. When a config is detected, docs-cache asks whether to sync references and stores the answer:

{
  "opencode": true
}

Declining stores "opencode": false and suppresses future prompts. It stops further management without changing existing OpenCode references. Omit the field only while no decision has been made. To target a specific project-local config, set a manual override such as "opencode": { "configPath": ".opencode/opencode.jsonc" }.

sync creates or updates managed OpenCode references whose aliases are source IDs. Paths are relative to the OpenCode config file:

{
  "references": {
    "framework": {
      "path": "../.docs/framework",
      "description": "Use for documentation from framework/core. Start with TOC.md."
    }
  }
}

The cache remains gitignored. targetDir, symlinks, copies, and unwrapped directories are never used for OpenCode reference paths. docs-cache preserves user-owned references and fails on an alias collision. A later sync removes stale managed aliases after a source is removed. When TOC generation is disabled for a source, its description does not direct OpenCode to TOC.md. sync --frozen validates references without writing the OpenCode config. Restart OpenCode after references change because it reads configuration at startup.

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 with compressed output. "tree" uses headings and links; false removes generated TOC files.
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 creates a symlink or copy pointing from the cache to that target directory. It is not enabled by default.

NPM Integration

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

{
  "scripts": {
    "postinstall": "npx docs-cache install"
  }
}

License

MIT