colmarius/with-agents

A multi-context Astro site for practical engineering: articles, generated slides, and source-backed resource collections for coding agents, cloud/GCP, security, and broader AI concepts, economics, and implications.
**Live site target**: with-agents.dev
Tech Stack
- **Astro v7** with React 19 islands
- **TailwindCSS v4**
- **Biome** for linting and formatting
- **GitHub Pages** deployment through GitHub Actions
Development
Use the Node.js version pinned in .nvmrc, matching CI. With nvm:
Before committing code or content changes, run:
**Build before testing:** some tests inspect the generated site and search
index in dist/. Testing first can check stale output or skip build-dependent
coverage. Run npm run preview to inspect the production build locally.
Run npm run hooks:install once per checkout to install the pinned prek
pre-commit hook. It validates timestamp citations only in staged summaries,
without network requests or rewriting content. Run npm run summaries:check
to check every summary; npm test also checks the full corpus in CI.
For content changes, follow the repository guidance and, for tracked
YouTube sources, the source-library publication rules.
Source-only evidence is committed but must not be published as site pages.
Site search
Use the Search button or ⌘/Ctrl+K on any page, including slides. Search covers
public field guides, summary text and resource descriptions. Drafts, unlisted
guides and duplicated slide content do not appear. Resources without summaries
lead to their owning catalog section. Catalog filtering remains separate.
Search requires a production build: run npm run build, then npm run preview.
The development server shows an explanation instead of loading an old index.
Each build extracts explicitly marked HTML into dist/search/documents.json
before generating the service worker. MiniSearch builds its in-memory index on
first opening in small yielding batches; subsequent queries stay in the browser. The complete corpus must
load successfully, otherwise the dialog offers Retry/Reload rather than partial
results. There is no query analytics or saved search history.
The installed site's service worker precaches search data and code, so search
works offline after installation. This downloads the corpus even if search has
not been opened. The existing update prompt reloads the site with the new corpus.
The site checks for deployments after service-worker registration, on return to
the page or reconnection, and every five minutes while visible and online.
Checks share a one-minute cooldown and do not overlap. Once a new offline snapshot
has finished installing, **Reload to update** activates it and reloads controlled
tabs together, keeping pages, assets, and search on the same deployment. Reading
is not interrupted by background discoveries. A browser refresh also accepts an
update already waiting or discovered by that refresh's startup check, once its
installation finishes. It checks for newer deployments even if an older update
is waiting. This prevents a hard refresh from showing fresh network
content only for the next normal refresh to return to an older offline snapshot.
Refresh consent expires after that check or installation; later discoveries
still show the prompt. Existing installations acquire this policy after accepting
their first update or loading the new page code with a hard refresh; offline or
suspended apps cannot discover deployments until they reconnect or resume.
Recently added
/recent/ mixes public posts, standalone resources, and individual collection or