The largest community release kage has had. Most of what is below arrived as pull requests from other people, and the rest came from bug reports that were specific enough to act on.

• --resume actually resumes. state.json only ever persisted the visited set, so a resumed run found its seed already visited, queued nothing, printed pages 0 and exited successfully with most of the site still missing. The unfinished frontier is now saved next to the visited set, with each page's depth so --max-depth keeps its meaning across a restart, and a run reports what it is leaving behind. A page that failed is carried into the next run instead of being lost, which is the memory of what failed asked for in #36. --max-pages no longer throws away the pages it held back, so inspecting a site with -p 20 and then finishing it later works as a workflow.
• Saved pages keep their doctype. kage serialises a rendered page as the outerHTML of <html>, and a doctype is a sibling of <html> rather than a child, so every page kage had ever written came out without one. A document with no doctype is quirks mode in every browser, which changes the box model and strips the <meta charset> declaration of its authority, and that is the encoding problem behind #16. The original doctype is now reproduced exactly, because the string itself selects the rendering mode, and a page that genuinely had none still gets none.
• Saved pages declare their real encoding. Non-UTF-8 <meta charset> and Content-Type charset declarations are rewritten to UTF-8, matching the bytes kage writes to disk (#16). Rewriting covers the whole document, but whether the page declares an encoding is answered from <head> alone, since a charset meta Chrome left in <body> sits past the 1024 bytes a reader pre-scans and is no use to anyone.
• --scroll scrolls the element that actually scrolls. It called window.scrollBy, which moves nothing on a site whose body is pinned to the viewport with the document inside an inner container, and that is how Feishu, Notion, Linear and most dashboards are built (#61). kage now picks the largest genuinely scrollable element, reads the position back after each step instead of assuming the step landed, and keeps going until both the position and the height stop changing. The whole scroll is bounded by half the render timeout, so a page that appends content forever cannot hold a worker.
• Redirects resolve correctly, and no longer end the crawl. Relative links use the post-redirect URL and the document's first <base href>, and every consumed base href is removed so it cannot re-root the saved page, while a base target is preserved. A redirect that leaves the crawl scope used to take the page's links with it: a seed redirecting apex to www resolved every link onto a host the scope rejects, so nothing was enqueued and the run saved one page and stopped, while assets kept downloading and made it look complete. The resolution base now falls back to the document <base href> and then to the enqueued URL whenever the redirect target is out of scope.
• Multi-page ZIM packs get a usable landing page. A mirror with no root index.html gets a bounded, title-sorted list of its pages instead of opening on an arbitrary one, and a single-page archive still opens directly on its article and keeps that article's title metadata (#62).
• Crawl path controls use path boundaries. --exclude and --scope-prefix match a path and its descendants rather than any substring, so pass the full path prefix if you relied on the old behaviour. --max-pages is now documented accurately as a cap on queued page URLs rather than on renders, so a page that fails, that robots.txt disallows, or that is not HTML still spends its slot.
• A headful crawl stops stealing focus. Render pages are created in the background, so driving kage through --control-url against a logged-in browser no longer pulls the Chrome window in front of whatever you are working in (#70).
• --traversal is deprecated. The flag was never read and crawls have always been breadth-first. It is still accepted so existing scripts keep working, and it is planned for removal in the next minor release.
• New documentation. CONTRIBUTING.md covers the development setup, the test commands, and what a focused pull request looks like, and a new robots.txt reference explains the kage agent token, Crawl-delay, and the advisory --no-robots override (#8).

Thanks

Special thanks to @SihanTeng, who wrote seven of the pull requests in this release: the redirect base resolution (#74), the synthetic ZIM landing page (#75), the crawl control path semantics (#76), the charset rewriting (#81), the --traversal deprecation (#82), the contributor guide (#83), and the robots.txt reference (#84). That work started as two large pull requests, and after a review asking for one concern each it came back as seven focused ones, which is the single most useful thing a contributor can do for a reviewer.

Thanks to @wangpi26 for the background render fix (#70), which is the kind of bug you only find by living with the tool.

Thanks to the people whose reports drove the rest of this release: @pepa65 for the UTF-8 and quirks mode report (#16), @j2l for the resume and long object chain report (#36), @edenzhong for the app-shell scrolling report (#61), @klerpi for the homepage-less ZIM report (#62), and @Xe for asking how site owners are meant to block this tool (#8).

Thanks also to everyone who has contributed to kage before this release: @Xirui, @zkd-11, @GautamKumarOffical, @Valid-Systems, and @AddictArts.

Changelog

Fixes

• cc82f04: fix: create render pages in background to avoid focus stealing (#70) (@wangpi26)

Other

• ec85d2f: Add a focused contributor guide (#83) (@SihanTeng)
• cbe5412: Add a synthetic ZIM landing page when root index is missing (#75) (@SihanTeng)
• 4533a71: Answer the charset declaration question from (#87) (@tamnd)
• 0b4eeda: Deprecate the ignored traversal flag (#82) (@SihanTeng)
• 62ae4e0: Describe --max-pages as a queue budget, not a render count (#85) (@tamnd)
• 110c00c: Document robots.txt controls for site owners (#84) (@SihanTeng)
• 0323633: Keep an out-of-scope redirect from stopping the crawl (#86) (@tamnd)
• 344d076: Keep the doctype so saved pages are not quirks mode (issue #16) (#78) (@tamnd)
• df48d4c: Persist the unfinished frontier so --resume resumes (issue #36) (#79) (@tamnd)
• 3583ec3: Release v0.3.12 (@tamnd)
• 4cc89d7: Resolve redirected-page links against the final URL (#74) (@SihanTeng)
• c996042: Rewrite stale charset declarations to UTF-8 (#81) (@SihanTeng)
• a233054: Scroll the element that actually scrolls (issue #61) (#80) (@tamnd)
• d7e6ab1: Use path-component semantics for crawl controls (#76) (@SihanTeng)

Changelog

Other

• 9d7abe1: Restore versioned Go installs without leakless (@tamnd)
• 25a6ebe: Update golang.org/x/text to v0.39.0 for GO-2026-5970 (@tamnd)

Changelog

Other

• 1ba8c89: Bump go toolchain to 1.26.5 (#71) (@tamnd)

Changelog

Other

• 7483efd: Dequarantine the brew cask binary on install (#67) (@tamnd)
• 35860d5: Drop the embedded leakless binary that trips antivirus (#69) (@tamnd)
• 320b21a: Pin release actions and cosign to fixed versions (#63) (@tamnd)
• 2dabb93: Run the container as root so a bind-mounted /out works (issue #7) (#53) (@tamnd)

What's changed

Fix: Windows binary no longer blocked by Defender

kage used go-rod's leakless launcher helper to guard Chrome processes, and that helper binary (leakless.exe) was being flagged as a trojan by Windows Defender (false positive, issues #7, #42). The fix disables leakless on Windows while leaving the Chrome cleanup path unchanged on all other platforms. The Windows binary now installs and runs cleanly with no AV interference.

Fix: brew install command now includes --cask

The README install snippet was missing --cask, so brew install kage would fail on a fresh machine. Fixed in the docs.

Feature: respect Crawl-delay from robots.txt during clone

When a site's robots.txt sets a Crawl-delay directive, kage now honors it between page fetches. This is a first step toward full crawl-rate control (#6); a --crawl-delay flag to override it from the command line is coming in a follow-up.

Upgrade

# Homebrew
brew upgrade kage

# Scoop
scoop update kage

# Docker
docker pull ghcr.io/tamnd/kage:0.3.8

Changelog

Fixes

• 9d452dd: fix: gofmt cli/clone.go (@tamnd)

Other

• 5ad8fff: Add the Linux apt/dnf repository to install docs and releases (@tamnd)
• 7157144: Document Homebrew and Scoop, and fix the deb/rpm filenames (@tamnd)
• a1b82eb: Make the Linux repo dispatch best-effort (@tamnd)
• e0e4096: Pin cosign to 2.x in the release workflow (#49) (@tamnd)
• 105e68f: Push the scoop manifest into the bucket directory (#52) (@tamnd)
• 910619b: Use index .Env for the optional tap and bucket tokens (#50) (@tamnd)
• 792878d: Use the bare .Env form for the tap and bucket tokens (#51) (@tamnd)

Changelog

Fixes

• 4e920c5: fix: correct mobile layout for paulgraham.com-style table pages (@tamnd)

Other

• c5b39d6: Cut the v0.3.6 release notes (@tamnd)

Changelog

Features

• 060b4b6: feat: add --mobile flag for readable archives of legacy sites (@tamnd)

Other

• 6655a43: Store each page under its real title in a packed ZIM (@tamnd)

Changelog

Fixes

• eb683dd: fix: continue rendering when Chrome hits 'Object reference chain is too long' ( <>)
• e80d38a: fix: kage serve Ctrl-C handling (@Xirui)
• c85745b: fix: serve Ctrl-C stop (@zkd-11)

Other

• 122a802: Cut the v0.3.4 release notes (@tamnd)

Changelog

Other

• a68d2b1: Cut the v0.3.3 release notes (@tamnd)
• bf850c6: Stop Chrome downloading files a crawl links to (@tamnd)