🗃️ 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.

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