v0.2.3 — documentation site and a tested city

v0.2.3

Released: 2026-10-24

Headline: documentation site and a tested city.

The documentation now has a home. tycoon has carried a full MkDocs site
since 0.1, built in strict mode on every pull request, but the result was
thrown away: nothing deployed it, and the URL in the repository returned a
404. From this release the site publishes to GitHub Pages whenever a
release reaches main, with internal pages kept out of it by a check that
fails the build rather than leaking them.

Underneath, the city renderer is now tested and gated like the CLI. The
vehicles and guests that were simulated but never drawn now drive, a
refresh repaints the whole screen, and the renderer's tests and its web
build run in CI. Alongside those: tycoon-city renders its help like
every other tycoon command, and tycoon's agent skills ship as three
installable Claude Code plugins.

Landed

The documentation site is published

• The site deploys to GitHub Pages. A new workflow builds the site
  whenever a release reaches main and publishes it at
  https://database-tycoon.github.io/tycoon-cli/. Because main only
  moves when a release merges, the published site always matches the
  released version. The three places in the repository that linked to the
  dead URL now resolve.
• Internal pages stay internal. City-renderer handover notes, agent
  task contracts and draft proposals live in the docs directory, and
  MkDocs used to build them, serve them at guessable URLs and index them
  for search. They are now withheld from the published build, while
  tycoon docs serve still renders them locally for contributors.
• A check stops anything leaking. After the strict build, a script
  confirms that no withheld page reached the site and that no published
  page links to one. A page that is in no list at all now fails the build
  instead of publishing silently.
• Releases have an index, and the sidebar is easier to scan. A
  releases page links the current release and the 0.2 series. The home
  page's Releases card points at it instead of the 0.1.5 notes, a Recipes
  card is added, and the City card links to the renderer notes on GitHub.
  The navigation is regrouped, with 0.2.x and 0.1.x releases folding away,
  and each page gets its own table of contents.

The city renderer is tested and gated

• Traffic actually drives. The animation loop simulated vehicles and
  guests but never updated the meshes that draw them, so streets stayed
  empty. Both now move. This was a known limitation in 0.2.0 through
  0.2.2.
• R refresh repaints everything. The footer, the notes popover and
  the legend were painted once at start-up, so a refresh showed new
  timestamps over the previous city's name, counts and legend.
• Unknown coverage reads as unknown, not 0%. For a catalog with no dbt
  manifest, the problems gauges, the library panel and the tour reported
  "columns documented 0%". They now show that coverage was never measured.
• The renderer is in CI. Its tests, including the city.json contract,
  run in the default pytest run and count toward coverage. A new web job
  typechecks the front end, builds it, checks that the bundle shipped in
  the wheel is exactly that build, and runs the Playwright suite. Until now
  the CLI was gated and the renderer was not.

Also in this release

• tycoon-city renders its help like every other tycoon command. The
  renderer's own command is now a Typer app with serve and demo
  subcommands, so tycoon-city demo --help and tycoon city --help look
  like the same tool. tycoon-city PATH still works as shorthand for
  serve.
• Agent skills install as Claude Code plugins. Three plugins ship from
  this repository's marketplace: tycoon, for working in a tycoon project
  (adding sources, diagnosing failures, reading pipeline state, building
  models and dashboards, operating pipelines), and tycoon-contributors
  and tycoon-maintainers, for working on tycoon itself. Install with
  /plugin marketplace add Database-Tycoon/tycoon-cli, then
  /plugin install tycoon@tycoon-skills. The skills are not part of the
  Python package.

Upgrading from 0.2.2

• Nothing to change in an existing project. No config format, command
  or default changed for projects.
• Scripts that call tycoon-city keep working. tycoon-city PATH and
  python -m tycoon_city.webserve [demo] behave as before. Only the help
  output changed.

Known limitations

• Run history's status column can't be fully trusted yet.
  tycoon data history marks a successful dbt build as failed when it
  includes no-op results (#341), and a dbt run that fails before it
  starts is never recorded at all (#377). Both are scheduled for 0.2.4.
• tycoon data status shows "last build never" for every dbt layer,
  even when data history lists the builds (#390). The fix is in review
  for 0.2.4.
• A few city HUD issues remain. The detail panel overlaps the legend,
  district labels can overlap, dbt sources outside the warehouse show as
  "upstream: none", and a skipped dbt test counts as a pass. Fixes for the
  first three are in review for 0.2.4 (#382 to #389), and #329 tracks the
  last.
• The legacy-table warning does not reach multi-resource sources.
  Migrating a flat filesystem source to the resources: shape leaves the
  old generic table behind without a warning
  (#244).
• Remote object storage is still unsupported. s3://, gs:// and
  az:// are recognised only well enough to be skipped by the local-glob
  check.

For contributors

• Documentation has publishing rules. CONTRIBUTING's new Documentation
  section says how a page is published, withheld or excluded, and which
  rules the build and the check enforce. A release now updates the
  releases index's current-release line by hand.
• The renderer's coverage counts. With tests/tycoon_city in the
  default run, the coverage floor was re-baselined to 73.
• The observability module is a package. observability.py, at 1,092
  lines, is split into src/tycoon/observability/ (store.py,
  dlt_capture.py, dbt_capture.py) with the public names re-exported,
  so imports are unchanged.
• The retired v5 city planner and its tests are gone.
• A MotherDuck roadmap is in docs/proposals/. It orders the
  local-to-MotherDuck work into four phases across 0.2.4 to 0.3.1, tracked
  in #429. It is a contributor page and is not published.

What's next

0.2.4 starts the MotherDuck work in #429: one is_motherduck() helper,
safer data query and data schema on MotherDuck, and raw ingestion into
an md: catalog. It also picks up the fixes that were ready but unreviewed
at this cut, among them data status showing each layer's last build
(#390), doctor telling a working .venv apart from a broken one (#392),
data query output formats (#391), the city HUD stack (#382 to #389), and
per-project dlt pipeline directories (#394).