Belkins/ai-dive-deep: Vlad's Playbook as a Buildable Astro Book

What Vlad's Playbook actually is, and who the repository is for

The README states the thesis plainly: stop sending dead files, and ship reports, pitches, audits and decks as live interactive HTML artifacts on a deployed link instead of PDF attachments. The book argues that position across 48 chapters, and the repository is meant to be the proof of it, since the book about building this kind of artifact is itself this kind of artifact.

The intended reader is an operator working with AI agents day to day, not a library consumer. The surfaces listed in the README are chapters, a radar page, an agent workflow page, a terminal setup page, a tier list, model files, a glossary of 89 terms, a cheat sheet and copy-paste resources. If you are looking for a package that adds agent orchestration to your own application, this is not that. It is a publication with a build pipeline attached, and the pipeline is the interesting engineering part.

How the Astro site, the widgets and the hourly radar fit together

The repository layout is conventional Astro with a heavy content layer. Chapters live in src/content/chapters/*.mdx, standalone pages in src/pages/, and 31 React or Astro widgets in src/widgets/, which the README lists as an Arena leaderboard, an AA economics panel, a sortable tier list, a command palette, a token-burn calculator, a swarm visualizer and a tokenizer lab, among others. Glossary terms sit in src/lib/glossary.ts, and research notes in src/lib/research-notes as dated entries.

The radar is the part with a real data flow. According to the README, a sibling pipeline pushes hourly, and the site rebuilds on every push, which the README gives as roughly 90 seconds via GitHub Pages. That rebuild is also what expires the homepage NEW badges: the README says they are derived from each page's git ship date, so nothing on the site claims to be new by hand. The changelog drives a dismissible what's new bar on every page.

The tier list takes a deliberately different stance on data. The README describes the Arena boards as hand-verified snapshots cross-checked against an independent community mirror, with Artificial Analysis figures traced to the page's own embedded JSON-LD and every capture date-stamped on the surface that shows it. That is a claim about provenance, and it is the kind of claim that usually rots quietly. Here it is checked at build time, which is the next section.

Running the prebuild guards locally

The most transferable idea in this repository is that the build fails on dishonesty. The package.json prebuild and predev scripts both run the same chain of Python and bash checks before Astro starts, covering stale numbers against a ledger, internal links, glossary drift, section IDs, template literals, the changelog, and chapter date generation. If you clone the repository, you need python3 and bash available before npm run dev will do anything useful.

Start by installing dependencies and running the guard chain on its own:

npm install
npm run prebuild

You should see the individual check scripts report in sequence, ending with gen-chapter-dates.py. A failure here stops the build, so a broken internal link or a stale figure is a build error rather than a review comment.

Individual guards can be run while you edit content, which is faster than the whole chain:

npm run lint:links
npm run lint:glossary
npm run lint:stale

The repository also exposes SEO and rendered-output checks, including check:radar for radar discovery and check:anchors for nested anchors. Analytics are optional and off by default: .env.example documents PUBLIC_POSTHOG_KEY as empty, with the comment that an absent key means no init, no events and no network calls, and PUBLIC_POSTHOG_HOST defaulting to https://us.i.posthog.com.

Where the guard-heavy approach costs you

Every one of those checks is a maintenance obligation. A stale-numbers guard needs a ledger to compare against, and the README says the tier-list snapshots are hand-verified, so someone has to keep verifying them. The changelog guard means the changelog is a build input, not a nice-to-have. If you fork this for your own book and delete the ledger, the guard has nothing to check and the value disappears with it.

The harder limitation is that the repository is a publication, not a reusable artifact. No recent releases were retrieved, the package is not described as published, and the agent workflow it documents lives in .claude/ and docs/workflow/ with configuration in .claude/workflow-kit.json. There is no install command for the workflow itself. If your goal is to add path-routed review agents to an existing codebase, you are reading a description of one team's setup, not adopting a tool.

The licence situation also warrants reading the file rather than the badge. The repository metadata reports NOASSERTION, while the README badge states code MIT and content CC BY-NC-SA 4.0. Those two statements are not the same, and the split matters if you want to reuse the prose. Check LICENSE directly and treat the content and the code as separate questions.

Astro Starlight and Docusaurus as the adjacent choice

If what you actually want is a documentation site with search and versioning, Astro Starlight and Docusaurus both target that directly, and both ship navigation, sidebars and search as defaults rather than as things you build. The difference in approach is where the custom logic sits. Starlight and Docusaurus give you a documentation shell and expect your content to fit it; ai-dive-deep gives you a general Astro site and expects you to write the 31 widgets, the radar pipeline and the guard scripts yourself, which is exactly what this repository did.

That trade is not obviously in ai-dive-deep's favour. You get a working reference for interactive artifacts and build-time verification, and you pay for it in surface area: 48 chapters, 50-plus pages, a widget directory, a scripts directory and a tests directory, all of which you now own. Choose the framework route if your content is conventional prose. Choose this repository as a model if the interactivity and the guards are the point.

Maintenance, upgrade cost and the licence split

The last push was on 2026-09-15, and the repository is not archived. The README shows an edition badge reading 13, which suggests the content is revised in numbered editions rather than semantic versions, and no releases were retrieved, so there is no changelog of tagged versions to diff against. Upgrading means pulling commits and re-running the prebuild chain, because the guards are the thing most likely to break when Astro, Tailwind or the widget dependencies move.

On licensing, the repository metadata says NOASSERTION and the README badge says code MIT with content CC BY-NC-SA 4.0. That distinction matters in practice: the guard scripts and widget code are one question, and the 48 chapters and 89 glossary terms are another. If you plan to reuse the prose in a commercial product, the non-commercial content licence is the constraint to read, and the LICENSE file is the authority rather than the badge.

Editorial conclusion

Clone it if you want a working example of a content repository that enforces its own claims at build time, or if you are writing an interactive technical book in Astro and want the guard scripts and widget patterns as a reference. Do not adopt it as a library: there is no published package, no versioned releases were retrieved, and the agent workflow it describes lives in .claude/ and docs/workflow/ rather than in an installable runtime. Before you commit to it, run the prebuild chain locally, since it depends on python3 and bash scripts that must pass before the site builds at all, and read the LICENSE file directly, because the repository reports NOASSERTION while the README badge states code MIT and content CC BY-NC-SA 4.0.

Frequently asked questions

Official sources

1. Belkins/ai-dive-deep on GitHub
2. Issues
3. Project website
4. README