Manage the local cache #

View this page as Markdown

These instructions are for an AI tool managing a local issue cache. The person does not need to maintain its files. Download and refresh issue files for local searches, then read the current issue from tzTrack before making a change.

Caching is optional. If local commands, curl, or tar are unavailable, read issues directly from tzTrack.

The Turn Zero connection lists tzTrack tools with tztrack_ before the name: find is tztrack_find. This page uses the shorter names. The tools lists the full names.

Prerequisites #

  • Confirm command access and check that curl and tar are available. In Windows PowerShell, use curl.exe to avoid its curl alias.
  • Select the intended space and determine the cache folder before writing files.
  • Read an existing index.md. Refresh it only if its second line is writer: tztrack; otherwise, read the cache without overwriting it.

Steps #

1. Find the folder #

For a Git repository, run this from the project folder:

git rev-parse --git-common-dir

Use local/tztrack/cache/ under the reported common Git folder. Resolve a relative result from the directory where you ran the command. Worktrees share this cache. Outside Git, use .tztrack/cache/ in the project folder.

Create the folder if needed. If its location cannot be determined safely, use live reads rather than guessing.

2. Download the issues #

Call cache for a download link, valid for ten minutes. Replace the placeholders below. Run the download first and check that it succeeded before unpacking:

curl -fsS -o tztrack-cache.tar.gz "<link>"
tar -xzf tztrack-cache.tar.gz -C "<cache folder>"

Treat the link as a credential and keep it out of reports. Delete the archive after a successful extraction. index.md comes last, but an extraction error still means the cache is incomplete; retry successfully or read live before using it.

3. Refresh the cache #

The first line of index.md reads # Issue cache, taken <timestamp>. Extract only the timestamp and pass it as since to cache; do not pass the whole heading.

Download the returned archive and confirm success before changing local files. Delete issues/<number>.md for each issue the response says is no longer available, then extract the changed files and fresh index.

A refresh overwrites matching files. Confirm extraction succeeded before trusting the new index.

4. Read the cache #

Search index.md and the issue files with your own file tools. The index lists open issues; each issue file starts with its state. Read the issue live with read before changing it, because another session may have updated it.

Expected result #

The folder contains one Markdown file per accessible issue, including closed issues, and an index of open issues. A successful refresh updates changed files, removes unavailable ones, and replaces the index.

Refusals #

Common refusals are below; Refusals lists the rest.

Refusal Status Cause Remedy
rate_limited 429 Too many requests; downloads also count. Wait for the rate window to reset, then retry.
invalid_request 400 A field is invalid, such as a malformed since. Pass the index's first-line timestamp as written.
space_mismatch 403 The account cannot access the selected space. Check the space and sign-in.
credential_required 401 Sign-in is incomplete. Complete sign-in through the AI tool.

An expired link returns 401. Request a new one with cache; do not retry the old link indefinitely.

  • The cache explains what the cache holds and why index.md comes last.
  • The tools lists cache and read.
  • Refusals lists every refusal.