hacktricks-cloud/AGENTS.md

AGENTS.md

Guidance for future agents working in this repository.

Repository Context

This is the HackTricks Cloud mdBook repository. The related main book lives at:

/Users/carlospolop/git/hacktricks

Changes to shared theme/search behavior often need to be applied in both repositories.

Search Index Loading Contract

The custom search UI lives in:

theme/ht_searcher.js

There may also be a generated copy at:

book/theme/ht_searcher.js

If production is deploying the already-built book/ directory, update both copies or rebuild the book before deployment.

The search index loading order is important and cost-sensitive:

1. Load every language-specific and fallback search index from the GitHub repository: HackTricks-wiki/hacktricks-searchindex
2. Only if all GitHub-hosted candidates fail, fall back to the same-origin mdBook output.

Do not place the local /searchindex.js fallback before any GitHub-hosted fallback such as searchindex-cloud-en.js.gz. Serving searchindex.js from cloud.hacktricks.wiki in production is expensive.

For this repo, the expected local fallback is:

/searchindex.js

The main-book fallback for this repo is:

/searchindex-book.js

That file is only a fallback. The primary source must remain the remote searchindex-<lang>.js.gz and searchindex-cloud-<lang>.js.gz files in HackTricks-wiki/hacktricks-searchindex.

Search Index Publishing

The workflows that publish encrypted compressed search indexes to HackTricks-wiki/hacktricks-searchindex are:

• .github/workflows/build_master.yml
• .github/workflows/translate_all.yml

The generated source file is book/searchindex.js. The published remote artifact names are:

• searchindex-cloud-en.js.gz
• searchindex-cloud-<lang>.js.gz

The browser loader expects the remote .js.gz files to be XOR-encrypted gzip payloads using the key defined in theme/ht_searcher.js.

Build And Validation

Common local checks:

• node --check theme/ht_searcher.js
• mdbook build

If mdbook build fails, check:

• hacktricks-preprocessor-error.log
• hacktricks-preprocessor.log

Editing Notes

• Prefer rg for searching.
• Keep generated book/ output out of commits unless explicitly requested. Search loader fixes are an exception when the already-built pages must be corrected immediately.
• If changing shared theme behavior, compare and update the matching file in /Users/carlospolop/git/hacktricks.
• Do not revert unrelated local changes.