kazam: Instructions file for Codex

AGENTS.md - developing kazam

For the YAML authoring guide (what kazam agents prints), see AGENTS.md.template.

Commands

cargo test --release --all-targets   # CI gate (always --release)
cargo fmt --all --check              # CI gate
cargo clippy --release --all-targets -- -D warnings  # CI gate; warnings = error
cargo build --release                # full build
./target/release/kazam dev docs --port 3002  # live-edit the docs site

CI runs these four jobs in parallel: test, fmt, clippy, cargo-audit.

Architecture

Single Rust binary. No workspace, no features, no build script. ~7 direct crates.

src/
  main.rs              CLI entry (clap derive): build, dev, init, agents, wish, track, ctx, board, workspace
  types.rs             All YAML-facing serde structs (SiteConfig, Page, Component, …)
  theme.rs             Theme tokens + STATIC_CSS (giant const string)
  render/
    mod.rs             Page render orchestration
    components.rs      Per-component render fns + dispatch match at top
    shells.rs          Shell chrome (standard, document, deck)
    scripts.rs         Bundled inline JS (deck nav, tabs, accordion, auto-fit)
    charts.rs          SVG chart rendering (pie, bar, timeseries)
    slug.rs            Anchor slug generation (used by section + header)
  build.rs             Batch build (yaml → html, copy assets)
  dev.rs               Watch + serve (notify + tiny_http)
  init.rs              kazam init scaffolding (KAZAM_YAML / INDEX_YAML / AGENTS_MD consts)
  agents.rs            kazam agents subcommand
  freshness.rs         Staleness computation (freshness: → banner + stale.md)
  links.rs             Link graph (orphan pages + broken internal hrefs)
  llms.rs              llms.txt emission
  minify.rs            Release-mode HTML/CSS/JS minification
  icons.rs             Bundled lucide icon SVGs
  wish/
    mod.rs             kazam wish dispatch (list, scaffold, grant, yolo)
    deck.rs            Deck wish (workspace + prompt generation)
    brief.rs           Brief wish
  workspace.rs         .kazam/ directory init, config read/write, atomic YAML persistence
  id.rs                Hash-based ID gen (kz-XXXX, no rand dep)
  board.rs             kazam board - live dashboard rendering .kazam/ state
  server.rs            Shared HTTP helpers: port binding, browser launch, responses, shutdown
  open.rs              kazam open, single-file browser viewer/editor for md/yaml/json
  show.rs              kazam show, single-file terminal pretty-printer for md/yaml/json
  track/
    mod.rs             kazam track CLI dispatch (11 subcommands)
    types.rs           Task, TaskStatus, TaskType, LogEntry, LogSeverity
    store.rs           YAML read/write for tasks + log
    graph.rs           Ready algorithm, dependency validation, cycle detection
  ctx/
    mod.rs             kazam ctx CLI dispatch (10 subcommands)
    types.rs           FileEntry, AnatomyStore, Learning, BugEntry
    scan.rs            Project file walker, token estimation, anatomy diff
    hooks.rs           Agent hook install/uninstall, shell script templates
docs/                  The hosted docs site (itself a kazam site)
examples/kb/           Example site used by integration tests
tests/integration.rs   E2e: invokes the binary, builds sites, asserts on HTML output
AGENTS.md.template     Authoring guide bundled via include_str! → kazam agents / kazam init