Deterministic audits over vibes

Wiki pages have no check-engine light. A page is created, someone updates it once, then three engineers leave and it sits there accumulating drift. Nobody's sure whether it's current. Nobody wants to be the one to fix it without knowing if it's even their responsibility.

This is the bystander effect in docs — diffuse ownership means effective ownership of zero.

kazam makes freshness opt-in per page. When you add it, you get deterministic tracking:

• owner: — free-form field, email, Slack handle, team name
• review_every: — 30d, 90d, quarterly, yearly — whatever makes sense for the content
• updated: — the ISO date of the last substantive change

At build time, kazam computes status. Yellow banner if a review is due within 7 days. Red banner if it's already overdue. _site/stale.md written on every build that finds anything stale — one file you can hand an agent and say "fix these."

No owner? No review_every? The page is always Fresh — there's nothing to compare against. You get as much rigor as you opt into, nothing more.

The context-switch problem is real. If updating docs means leaving the IDE, logging into a browser, navigating a wiki UI, finding the right page, and remembering what the old content said — it won't happen. Engineers are not lazy; they are busy, and the friction is too high.

kazam lives in the repo. YAML files sit next to the code they document. The CLI builds locally. The same PR that changes behavior can update the doc in one commit.

One deliberate decision: the build does not fail on stale content. It flags it. The right amount of nudge is a banner and a build report — not a broken CI pipeline that blocks a deploy because someone forgot to update a date field. Blocking deploys on doc staleness would teach engineers to remove the freshness metadata, which is the opposite of what you want.

If you want stricter enforcement, wire _site/stale.md into your own CI gate. That choice belongs to your team.

AI agents burn tokens scraping HTML, guessing at structure, handling auth, parsing wiki exports. The output is brittle. The pages have no schema, so the agent invents one and gets it half right.

kazam ships an MCP server with 8 tools:

Agents query structured YAML directly — the same source that builds the site. No HTML parsing. No export pipeline. The schema is the file.

The MCP server runs over stdio (for local agents) or HTTP with bearer token auth (for remote/team access). Prompt templates give agents consistent instructions for the content lifecycle: migrate, refresh, audit, review. Standardized workflows mean you can hand any agent the same template and get predictable results.

Someone mentions a competitive threat on a customer call. It lives in the call transcript, maybe a Slack thread, maybe someone's personal notes. It never makes it into the doc that matters — the customer page, the competitive brief, the deal tracker.

kazam's sidecar annotations capture this context at the moment it happens:

Annotations live as individual YAML files in .kazam/annotations/ — not embedded in the page, so there are no write collisions or round-trip serialization issues. They render inline at build time with age indicators and status badges.

The real power is the refresh loop. When an agent refreshes a page, it reads pending annotations first — as the highest-priority source. Human context overrides stale CRM data. After incorporating an annotation, the agent marks it incorporated. A 14-day decay window ensures nothing sits unreviewed forever.

Most documentation toolchains: Node, React, MDX, a build pipeline, webpack or Vite, a handful of config files, version pins, and a node_modules that weights 400 MB. Getting a new engineer running takes an afternoon if anything is mismatched.

kazam is a single Rust binary. Install it once:

Point it at a folder, get static HTML:

The output is plain HTML and CSS — no runtime JavaScript. Host it anywhere: S3, GitHub Pages, Firebase Hosting, any web server that can serve static files. The binary builds; your host serves. Nothing else in the chain.

Engineers trust docs that admit limitations. Here are kazam's:

No WYSIWYG editor. Content lives in YAML files. If your team can't comfortably edit YAML in VS Code, kazam is not the right tool.

No real-time collaboration. The workflow is Git: branch, edit, PR, merge. If your team needs multiple people editing the same page simultaneously, use Notion or Confluence.

No hosted SaaS (yet). You manage the binary, you own the hosting. For some teams that's a feature; for others it's work they don't want.

No ecosystem of templates and integrations. kazam is a CLI tool, not a platform. There are no third-party plugins, no marketplace, no Zapier connection. What you see in these docs is what exists.

The honest framing: keep using Notion for brainstorming, project management, and freeform collaboration. kazam is for technical truth — the docs that must be right for the system to work. Architecture decision records, runbooks, API references, onboarding guides. The things that go stale and stay stale.

This is a partial picture — all tools have strengths outside this table. The purpose is to show where kazam is differentiated, not to score every dimension.